@stll/folio-core 0.49.0 → 0.51.0

package/dist/compare/content.js

@@ -431,30 +431,61 @@ const separatorBetween = (whole, head, tail) => {
 	const separator = whole.slice(head.length, whole.length - tail.length);
 	return separator.length === 0 || /^\s+$/u.test(separator) ? separator : null;
 };
+const splitPlan = ({ baseBlock, head, tail }) => {
+	const separator = separatorBetween(baseBlock.text, head.text, tail.text);
+	return separator !== null && contentBlocksShareContainer(head, tail) ? {
+		type: "split",
+		baseBlock,
+		revisedBlocks: [head, tail],
+		offset: head.text.length,
+		separator
+	} : null;
+};
+const mergePlan = ({ revisedBlock, head, tail }) => {
+	const separator = separatorBetween(revisedBlock.text, head.text, tail.text);
+	return separator !== null && contentBlocksShareContainer(head, tail) ? {
+		type: "merge",
+		baseBlocks: [head, tail],
+		revisedBlock,
+		separator
+	} : null;
+};
+/**
+* A pair next to a one-sided block its text spells together with the pair's
+* other side. Alignment pairs a split paragraph with whichever half reads more
+* like it, so the unpaired half may stand before the pair or after it.
+*/
+const paragraphMarkPlan = (step, next) => {
+	if (step.type === "pair" && next.type === "revisedOnly") return splitPlan({
+		baseBlock: step.baseBlock,
+		head: step.revisedBlock,
+		tail: next.block
+	});
+	if (step.type === "pair" && next.type === "baseOnly") return mergePlan({
+		revisedBlock: step.revisedBlock,
+		head: step.baseBlock,
+		tail: next.block
+	});
+	if (step.type === "revisedOnly" && next.type === "pair") return splitPlan({
+		baseBlock: next.baseBlock,
+		head: step.block,
+		tail: next.revisedBlock
+	});
+	if (step.type === "baseOnly" && next.type === "pair") return mergePlan({
+		revisedBlock: next.revisedBlock,
+		head: step.block,
+		tail: next.baseBlock
+	});
+	return null;
+};
+/** Plans keyed by their first step; each consumes the step after it. */
 const detectFolioContentParagraphMarkPlans = (steps) => {
 	const plans = /* @__PURE__ */ new Map();
 	for (const [index, step] of steps.entries()) {
 		const next = steps[index + 1];
-		if (step.type !== "pair" || next === void 0) continue;
-		if (next.type === "revisedOnly") {
-			const separator = separatorBetween(step.baseBlock.text, step.revisedBlock.text, next.block.text);
-			if (separator !== null && contentBlocksShareContainer(step.revisedBlock, next.block)) plans.set(index, {
-				type: "split",
-				baseBlock: step.baseBlock,
-				revisedBlocks: [step.revisedBlock, next.block],
-				offset: step.revisedBlock.text.length,
-				separator
-			});
-			continue;
-		}
-		if (next.type !== "baseOnly") continue;
-		const separator = separatorBetween(step.revisedBlock.text, step.baseBlock.text, next.block.text);
-		if (separator !== null && contentBlocksShareContainer(step.baseBlock, next.block)) plans.set(index, {
-			type: "merge",
-			baseBlocks: [step.baseBlock, next.block],
-			revisedBlock: step.revisedBlock,
-			separator
-		});
+		if (next === void 0 || plans.has(index - 1)) continue;
+		const plan = paragraphMarkPlan(step, next);
+		if (plan !== null) plans.set(index, plan);
 	}
 	return plans;
 };

package/dist/display-list/dom/renderDisplayListToDom.d.ts

@@ -1,10 +1,19 @@
 import { DisplayColor, DisplayFontFace, DisplayImageSource, DisplayList, DisplayPage } from "../types.js";
 //#region src/display-list/dom/renderDisplayListToDom.d.ts
+/**
+ * How the backend addresses image and embedded-font bytes: `objectUrl` mints
+ * a `blob:` URL where the runtime can (a live page, which revokes them), and
+ * `dataUrl` always inlines the bytes (markup that leaves the process, such as
+ * a serialized page, where a `blob:` URL would resolve to nothing).
+ */
+type DisplayBinaryUrls = "objectUrl" | "dataUrl";
 type RenderDisplayListOptions = {
   /** Document to create elements in. */
   readonly doc: Document;
   /** Page background, painted before any primitive. */
   readonly pageBackground?: DisplayColor;
+  /** Defaults to `objectUrl`. */
+  readonly binaryUrls?: DisplayBinaryUrls;
 };
 /**
  * A page's glyph runs and images index tables that live on the list, and an
@@ -23,4 +32,4 @@ declare const renderDisplayPageToDom: (page: DisplayPage, options: RenderDisplay
 /** One `div.layout-page` per display page, in page order. */
 declare const renderDisplayListToDom: (list: DisplayList, options: RenderDisplayListOptions) => HTMLElement[];
 //#endregion
-export { RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };
+export { DisplayBinaryUrls, RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };

package/dist/display-list/dom/renderDisplayListToDom.js

@@ -103,8 +103,8 @@ const resolveImage = (ref, images) => {
 };
 /** A `Blob` part cannot be backed by shared memory, so prove it is not. */
 const isBlobPart = (bytes) => bytes.buffer instanceof ArrayBuffer;
-const binarySrc = (bytes, mimeType) => {
-	if (isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
+const binarySrc = (bytes, mimeType, urls) => {
+	if (urls === "objectUrl" && isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
 	return bytesToDataUrl(bytes, mimeType);
 };
 const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quoteFontFamily(embedded.id)}; src: url("${src}"); font-weight: ${face.weight}; font-style: ${face.italic ? "italic" : "normal"}; }`;
@@ -113,14 +113,14 @@ const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quote
 * once per render and shared by every page: an id maps to one blob, so the
 * bytes are held once and one revoke releases them.
 */
-const embeddedFontFaceCss = (fonts) => {
+const embeddedFontFaceCss = (fonts, urls) => {
 	const srcById = /* @__PURE__ */ new Map();
 	const rules = [];
 	for (const face of fonts) {
 		const embedded = face.embedded;
 		if (embedded === void 0) continue;
 		const cached = srcById.get(embedded.id);
-		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE);
+		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE, urls);
 		if (cached === void 0) srcById.set(embedded.id, src);
 		rules.push(fontFaceRule(face, embedded, src));
 	}
@@ -399,7 +399,7 @@ const paintImage = ({ image, rect, crop, opacity, brightness, contrast }, contex
 		element.style.height = px(fullHeight);
 	}
 	element.alt = "";
-	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format]);
+	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format], context.binaryUrls);
 	clip.append(element);
 	context.parent.append(clip);
 };
@@ -497,6 +497,7 @@ const renderPage = (page, options) => {
 	}
 	const context = {
 		doc: options.doc,
+		binaryUrls: options.binaryUrls ?? "objectUrl",
 		fonts: options.fonts,
 		images: options.images,
 		parent: element,
@@ -595,11 +596,11 @@ const paintRegionTree = ({ primitives, regions }, context) => {
 };
 const renderDisplayPageToDom = (page, options) => renderPage(page, {
 	...options,
-	fontFaceCss: embeddedFontFaceCss(options.fonts)
+	fontFaceCss: embeddedFontFaceCss(options.fonts, options.binaryUrls ?? "objectUrl")
 });
 /** One `div.layout-page` per display page, in page order. */
 const renderDisplayListToDom = (list, options) => {
-	const fontFaceCss = embeddedFontFaceCss(list.fonts);
+	const fontFaceCss = embeddedFontFaceCss(list.fonts, options.binaryUrls ?? "objectUrl");
 	return list.pages.map((page, pageIndex) => renderPage(page, {
 		...options,
 		fonts: list.fonts,

package/dist/display-list/html/renderDisplayListToHtml.d.ts

@@ -0,0 +1,21 @@
+import { DisplayColor, DisplayList } from "../types.js";
+//#region src/display-list/html/renderDisplayListToHtml.d.ts
+declare const escapeHtmlText: (value: string) => string;
+type RenderDisplayListToHtmlOptions = {
+  /** `@font-face` rules for the families the list names, placed in the head. */
+  readonly fontFaceCss?: string;
+  /** The document title. */
+  readonly title?: string;
+  /** Space between pages. Defaults to 0: pages stack flush. */
+  readonly pageGapPx?: number;
+  /** CSS color behind the pages. Defaults to white. */
+  readonly canvasColor?: string;
+  /** Page background, painted before any primitive. */
+  readonly pageBackground?: DisplayColor;
+};
+/** The pages' markup, one slot per display page, in page order. */
+declare const renderDisplayListPagesToHtml: (list: DisplayList, options?: Pick<RenderDisplayListToHtmlOptions, "pageBackground">) => string[];
+/** A complete HTML document showing every page of the list. */
+declare const renderDisplayListToHtml: (list: DisplayList, options?: RenderDisplayListToHtmlOptions) => string;
+//#endregion
+export { RenderDisplayListToHtmlOptions, escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/html/renderDisplayListToHtml.js

@@ -0,0 +1,126 @@
+import { renderDisplayListToDom } from "../dom/renderDisplayListToDom.js";
+//#region src/display-list/html/renderDisplayListToHtml.ts
+/**
+* A display list as one HTML document, with no browser and no DOM.
+*
+* The DOM backend paints into whatever `Document` it is handed. This module
+* hands it a document with only what the backend reaches for and serializes
+* the result, so a server, a CLI or a harness can produce the page a browser
+* would show from the same painter the editor uses. Binary data (images,
+* embedded faces) is inlined as `data:` URLs, because a `blob:` URL minted in
+* this process resolves to nothing once the markup leaves it.
+*/
+const VOID_TAGS = /* @__PURE__ */ new Set([
+	"img",
+	"br",
+	"hr"
+]);
+const createStubElement = (tagName) => {
+	const children = [];
+	const attributes = {};
+	return {
+		tagName,
+		style: {},
+		dataset: {},
+		attributes,
+		children,
+		className: "",
+		id: "",
+		textContent: "",
+		alt: "",
+		src: "",
+		href: "",
+		title: "",
+		append: (...nodes) => {
+			children.push(...nodes);
+		},
+		appendChild: (node) => {
+			children.push(node);
+			return node;
+		},
+		setAttribute: (name, value) => {
+			attributes[name] = value;
+		}
+	};
+};
+/**
+* A `Document` with only what the DOM backend reaches for. A backend that
+* grows a new requirement throws on the missing property here rather than
+* silently serializing less than it painted.
+*/
+const stubDocument = () => {
+	return { createElement: createStubElement };
+};
+const asStub = (element) => element;
+/** A vendor property is camelCase with no leading capital, so its leading dash is explicit. */
+const VENDOR_PREFIXES = [
+	"webkit-",
+	"moz-",
+	"ms-",
+	"o-"
+];
+const toKebabCase = (name) => {
+	const hyphenated = name.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+	return VENDOR_PREFIXES.some((prefix) => hyphenated.startsWith(prefix)) ? `-${hyphenated}` : hyphenated;
+};
+const escapeHtmlText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const escapeAttribute = (value) => escapeHtmlText(value).replaceAll("\"", "&quot;");
+const serializeStyle = (style) => Object.entries(style).map(([property, value]) => `${toKebabCase(property)}: ${value}`).join("; ");
+/**
+* Serialized without one character of added whitespace: the backend sets
+* `white-space: pre` on every run, so an indentation newline would be painted.
+*/
+const RAW_TEXT_TAGS = /* @__PURE__ */ new Set(["style", "script"]);
+/** Text placed inside a `<style>` or `<script>`: a `</` cannot close the element early. */
+const rawElementText = (text) => text.replaceAll("</", "<\\/");
+const serializeElement = (element) => {
+	const attributes = [];
+	if (element.className !== "") attributes.push(`class="${escapeAttribute(element.className)}"`);
+	if (element.id !== "") attributes.push(`id="${escapeAttribute(element.id)}"`);
+	if (element.href !== "") attributes.push(`href="${escapeAttribute(element.href)}"`);
+	if (element.src !== "") attributes.push(`src="${escapeAttribute(element.src)}"`);
+	if (element.title !== "") attributes.push(`title="${escapeAttribute(element.title)}"`);
+	if (element.tagName === "img") attributes.push(`alt="${escapeAttribute(element.alt)}"`);
+	for (const [name, value] of Object.entries(element.attributes)) attributes.push(`${name}="${escapeAttribute(value)}"`);
+	for (const [key, value] of Object.entries(element.dataset)) attributes.push(`data-${toKebabCase(key)}="${escapeAttribute(value)}"`);
+	const style = serializeStyle(element.style);
+	if (style !== "") attributes.push(`style="${escapeAttribute(style)}"`);
+	const open = [element.tagName, ...attributes].join(" ");
+	if (VOID_TAGS.has(element.tagName)) return `<${open} />`;
+	if (element.children.length > 0) return `<${open}>${element.children.map(serializeElement).join("")}</${element.tagName}>`;
+	return `<${open}>${RAW_TEXT_TAGS.has(element.tagName) ? rawElementText(element.textContent) : escapeHtmlText(element.textContent)}</${element.tagName}>`;
+};
+/**
+* Each page sits in a slot of whole pixels. A page height is fractional (A4 is
+* 1122.52 px), so pages stacked in normal flow would start at fractional
+* offsets; the slot rounds the offset while the page keeps its exact size.
+*/
+const pageSlot = (markup, page) => `<div class="layout-page-slot" style="position: relative; overflow: hidden; width: ${String(Math.ceil(page.widthPx))}px; height: ${String(Math.ceil(page.heightPx))}px">${markup}</div>`;
+/** The pages' markup, one slot per display page, in page order. */
+const renderDisplayListPagesToHtml = (list, options = {}) => renderDisplayListToDom(list, {
+	doc: stubDocument(),
+	binaryUrls: "dataUrl",
+	...options.pageBackground !== void 0 && { pageBackground: options.pageBackground }
+}).map((element, index) => {
+	const markup = serializeElement(asStub(element));
+	const page = list.pages.at(index);
+	return page === void 0 ? markup : pageSlot(markup, page);
+});
+/** A complete HTML document showing every page of the list. */
+const renderDisplayListToHtml = (list, options = {}) => {
+	const gap = options.pageGapPx ?? 0;
+	const canvas = rawElementText(options.canvasColor ?? "#fff");
+	const layout = gap > 0 ? `body { display: flex; flex-direction: column; align-items: center; gap: ${String(gap)}px; padding: ${String(gap)}px 0; }` : "";
+	return [
+		"<!doctype html>",
+		`<html><head><meta charset="utf-8"><title>${escapeHtmlText(options.title ?? "")}</title><style>`,
+		rawElementText(options.fontFaceCss ?? ""),
+		`html, body { margin: 0; padding: 0; background: ${canvas}; }`,
+		layout,
+		"</style></head><body>",
+		renderDisplayListPagesToHtml(list, options).join(""),
+		"</body></html>"
+	].join("\n");
+};
+//#endregion
+export { escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/selectDisplayPages.d.ts

@@ -0,0 +1,6 @@
+import { DisplayList } from "./types.js";
+//#region src/display-list/selectDisplayPages.d.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+declare const selectDisplayPages: (list: DisplayList, pageIndices: readonly number[]) => DisplayList;
+//#endregion
+export { selectDisplayPages };

package/dist/display-list/selectDisplayPages.js

@@ -0,0 +1,44 @@
+//#region src/display-list/selectDisplayPages.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+const selectDisplayPages = (list, pageIndices) => {
+	const kept = [...new Set(pageIndices)].filter((index) => Number.isInteger(index) && index >= 0 && index < list.pages.length);
+	const remap = new Map(kept.map((original, next) => [original, next]));
+	const relink = (link) => {
+		if (link.target.kind !== "page") return [link];
+		const pageIndex = remap.get(link.target.pageIndex);
+		return pageIndex === void 0 ? [] : [{
+			...link,
+			target: {
+				...link.target,
+				pageIndex
+			}
+		}];
+	};
+	const pages = kept.flatMap((index) => {
+		const page = list.pages[index];
+		return page === void 0 ? [] : [{
+			...page,
+			links: page.links.flatMap(relink)
+		}];
+	});
+	return {
+		...list,
+		pages,
+		outline: list.outline.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		}),
+		unsupported: list.unsupported.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		})
+	};
+};
+//#endregion
+export { selectDisplayPages };

package/dist/docx/selectiveSave.d.ts

@@ -3,7 +3,7 @@ import { document_d_exports } from "../types/document.js";
 type SelectiveSaveOptions = {
   /** Changed paragraph IDs to selectively patch */
   changedParaIds: Set<string>;
-  /** Whether structural changes occurred (paragraph add/delete) */
+  /** Whether paragraph membership, order, or block structure changed. */
   structuralChange: boolean;
   /** Whether any changes affected paragraphs without paraId */
   hasUntrackedChanges: boolean;

package/dist/docx/selectiveSave.js

@@ -8,12 +8,13 @@ import { isUnsafePackagePath } from "./packageParts.js";
 import { RELATIONSHIP_TYPES } from "./relsParser.js";
 import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
 import "./selectiveSaveFlags.js";
-import { buildPatchedDocumentXml, buildPatchedNoteXml, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
+import { buildPatchedDocumentXml, buildPatchedNoteXml, collectAddedNumberingDefs, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
 import { planCommentParts, 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 { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
+import { buildStructuralDocumentPatch } from "./structuralXmlPatch.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/selectiveSave.ts
 /**
@@ -174,7 +175,6 @@ const queueSettingsUpdates = async (zip, updates) => {
 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;
@@ -197,22 +197,32 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
 		const updates = /* @__PURE__ */ new Map();
-		if (changedParaIds.size > 0) {
+		if (changedParaIds.size > 0 || structuralChange) {
 			const docXmlFile = zip.file("word/document.xml");
 			if (!docXmlFile) return null;
 			const originalDocXml = await docXmlFile.async("text");
 			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml));
 			const bodyParaIds = collectParaIds(serializedDocXml);
+			const originalBodyParaIds = structuralChange ? collectParaIds(originalDocXml) : void 0;
+			if (structuralChange && doc.package.numbering) {
+				const numberingFile = findZipEntryCaseInsensitive(zip, "word/numbering.xml");
+				const added = collectAddedNumberingDefs(numberingFile ? serializeNumberingXml(parseNumbering(await numberingFile.async("text")).definitions) : "", serializeNumberingXml(doc.package.numbering));
+				if (added.abstractNums.size > 0 || added.nums.size > 0) return null;
+			}
 			const bodyChangedIds = /* @__PURE__ */ new Set();
 			const noteCandidateIds = /* @__PURE__ */ new Set();
-			for (const id of changedParaIds) if (bodyParaIds.has(id)) bodyChangedIds.add(id);
+			for (const id of changedParaIds) if (bodyParaIds.has(id) || originalBodyParaIds?.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, serializedDocXml, bodyChangedIds);
+			if (bodyChangedIds.size > 0 || structuralChange) {
+				const patchedDocXml = structuralChange ? buildStructuralDocumentPatch({
+					originalXml: originalDocXml,
+					serializedXml: serializedDocXml,
+					changedIds: bodyChangedIds
+				}) : buildPatchedDocumentXml(originalDocXml, serializedDocXml, bodyChangedIds);
 				if (!patchedDocXml) return null;
 				updates.set("word/document.xml", patchedDocXml);
 			}

package/dist/docx/structuralXmlPatch.d.ts

@@ -0,0 +1,14 @@
+//#region src/docx/structuralXmlPatch.d.ts
+type StructuralPatchOptions = {
+  originalXml: string;
+  serializedXml: string;
+  changedIds: ReadonlySet<string>;
+};
+/**
+ * Insert/delete direct body paragraphs between surviving paragraph/table anchors.
+ * Tables are opaque barriers: their modeled content and order must stay identical.
+ * Id-less sources need an explicit ensureParaIds ingest before structural editing.
+ */
+declare const buildStructuralDocumentPatch: ({ originalXml, serializedXml, changedIds }: StructuralPatchOptions) => string | null;
+//#endregion
+export { buildStructuralDocumentPatch };

package/dist/docx/structuralXmlPatch.js

@@ -0,0 +1,209 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { parseDocumentBody } from "./documentParser.js";
+import { paraIdAttribute } from "./paraIdAttribute.js";
+import { spliceXml } from "./selectiveXmlPatch.js";
+import { readRootNamespaceBindings, serializePartElement } from "./serializer/partNamespaces.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+//#region src/docx/structuralXmlPatch.ts
+/** Conservative body-paragraph splices; source offsets never come from reserialization. */
+const isWordElement = (element, name) => getLocalName(element.name) === name && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "");
+/** Match XML tokens, skipping quoted delimiters, comments, CDATA and processing instructions. */
+const XML_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<(?:"[^"]*"|'[^']*'|[^'">])*>/gu;
+const readBody = (xml) => {
+	const root = parseXmlDocument(xml);
+	if (!root || !isWordElement(root, "document")) return null;
+	if (getNamespaceUri(root) !== NAMESPACES.w) return null;
+	const body = getChildElements(root).find((child) => isWordElement(child, "body"));
+	if (!body) return null;
+	const children = getChildElements(body);
+	const blocks = [];
+	const stack = [];
+	let bodyDepth = -1;
+	let bodyEnd = -1;
+	let start = -1;
+	for (const token of xml.matchAll(XML_TOKEN)) {
+		const tag = token[0];
+		if (tag.startsWith("<!") || tag.startsWith("<?")) continue;
+		const closing = tag.startsWith("</");
+		const name = tag.slice(closing ? 2 : 1).split(/[\s/>]/u).at(0);
+		if (!name) return null;
+		if (closing) {
+			if (stack.pop() !== name) return null;
+			if (stack.length === bodyDepth) {
+				const element = children[blocks.length];
+				if (!element || start < 0) return null;
+				blocks.push({
+					element,
+					start,
+					end: token.index + tag.length
+				});
+				start = -1;
+			}
+			if (name === body.name && stack.length === bodyDepth - 1) bodyEnd = token.index;
+			continue;
+		}
+		if (name === body.name && stack.length === 1) bodyDepth = 2;
+		if (stack.length === bodyDepth) {
+			if (children[blocks.length]?.name !== name) return null;
+			start = token.index;
+			if (tag.endsWith("/>")) {
+				const element = children[blocks.length];
+				if (!element) return null;
+				blocks.push({
+					element,
+					start,
+					end: token.index + tag.length
+				});
+				start = -1;
+			}
+		}
+		if (!tag.endsWith("/>")) stack.push(name);
+	}
+	if (stack.length > 0 || blocks.length !== children.length || bodyEnd < 0) return null;
+	return {
+		root,
+		blocks,
+		bodyEnd
+	};
+};
+function* descendants(element) {
+	yield element;
+	for (const child of getChildElements(element)) yield* descendants(child);
+}
+/** Cross-paragraph ranges require a wider edit contract than paragraph identity. */
+const RANGE_ELEMENTS = /* @__PURE__ */ new Set([
+	"commentRangeStart",
+	"commentRangeEnd",
+	"commentReference",
+	"bookmarkStart",
+	"bookmarkEnd",
+	"permStart",
+	"permEnd",
+	"fldChar",
+	"moveFromRangeStart",
+	"moveFromRangeEnd",
+	"moveToRangeStart",
+	"moveToRangeEnd"
+]);
+const DEPENDENT_ELEMENTS = /* @__PURE__ */ new Set([
+	"sectPr",
+	"footnoteReference",
+	"endnoteReference",
+	"drawing",
+	"pict",
+	"object"
+]);
+const paragraphIsSafe = (element, touched) => {
+	for (const child of descendants(element)) {
+		if (!WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) continue;
+		const name = getLocalName(child.name);
+		if (touched && DEPENDENT_ELEMENTS.has(name)) return false;
+	}
+	return true;
+};
+const paragraphIds = (root) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const element of descendants(root)) {
+		if (!isWordElement(element, "p")) continue;
+		const id = paraIdAttribute(element);
+		if (!id || !/^[0-9a-f]{8}$/iu.test(id) || /^0+$/u.test(id) || ids.has(id.toUpperCase())) return null;
+		ids.add(id.toUpperCase());
+	}
+	return ids;
+};
+/** Bind fragment prefixes locally: the source root may use entirely different aliases. */
+const paragraphFragment = ({ xml, block, bindings }) => {
+	const fragment = xml.slice(block.start, block.end);
+	const openEnd = fragment.indexOf(">");
+	const name = block.element.name ?? "w:p";
+	const selfClosing = fragment[openEnd - 1] === "/";
+	return serializePartElement({
+		partPath: "word/document.xml",
+		rootName: name,
+		rootAttributes: fragment.slice(name.length + 1, selfClosing ? openEnd - 1 : openEnd).trim(),
+		baselinePrefixes: [],
+		sourceBindings: bindings,
+		body: selfClosing ? "" : fragment.slice(openEnd + 1, fragment.lastIndexOf("</"))
+	});
+};
+/**
+* Insert/delete direct body paragraphs between surviving paragraph/table anchors.
+* Tables are opaque barriers: their modeled content and order must stay identical.
+* Id-less sources need an explicit ensureParaIds ingest before structural editing.
+*/
+const buildStructuralDocumentPatch = ({ originalXml, serializedXml, changedIds }) => {
+	const source = readBody(originalXml);
+	const current = readBody(serializedXml);
+	if (!source || !current) return null;
+	for (const root of [source.root, current.root]) for (const element of descendants(root)) if (WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "") && RANGE_ELEMENTS.has(getLocalName(element.name))) return null;
+	const allSourceIds = paragraphIds(source.root);
+	const allCurrentIds = paragraphIds(current.root);
+	if (!allSourceIds || !allCurrentIds) return null;
+	const changed = new Set([...changedIds].map((id) => id.toUpperCase()));
+	for (const { element } of [...source.blocks, ...current.blocks]) if (isWordElement(element, "p")) {
+		const id = paraIdAttribute(element)?.toUpperCase();
+		if (!id) return null;
+		const touched = changed.has(id) || !allSourceIds.has(id) || !allCurrentIds.has(id);
+		if (!paragraphIsSafe(element, touched)) return null;
+	} else if (!isWordElement(element, "tbl") && !isWordElement(element, "sectPr")) return null;
+	const sourceBody = parseDocumentBody(originalXml);
+	const currentBody = parseDocumentBody(serializedXml);
+	const barriers = (body) => ({
+		blocks: body.content.filter((block) => block.type !== "paragraph"),
+		finalSectionProperties: body.finalSectionProperties,
+		background: body.background
+	});
+	if (canonicalJson(barriers(sourceBody)) !== canonicalJson(barriers(currentBody))) return null;
+	const indexBlocks = (blocks) => {
+		let barrier = 0;
+		const indexed = /* @__PURE__ */ new Map();
+		for (const block of blocks) {
+			const key = isWordElement(block.element, "p") ? `p:${paraIdAttribute(block.element)?.toUpperCase()}` : `barrier:${barrier++}`;
+			indexed.set(key, block);
+		}
+		return indexed;
+	};
+	const before = indexBlocks(source.blocks);
+	const after = indexBlocks(current.blocks);
+	const survivingBefore = [...before.keys()].filter((key) => after.has(key));
+	const survivingAfter = [...after.keys()].filter((key) => before.has(key));
+	if (canonicalJson(survivingBefore) !== canonicalJson(survivingAfter)) return null;
+	const bindings = readRootNamespaceBindings(serializedXml);
+	const fragmentFor = (block) => paragraphFragment({
+		xml: serializedXml,
+		block,
+		bindings
+	});
+	const splices = [];
+	for (const [key, block] of before) if (!after.has(key)) splices.push({
+		start: block.start,
+		end: block.end,
+		newXml: ""
+	});
+	let pending = [];
+	for (const [key, block] of after) {
+		const original = before.get(key);
+		if (!original) {
+			const id = paraIdAttribute(block.element)?.toUpperCase();
+			if (!id || allSourceIds.has(id)) return null;
+			pending.push(fragmentFor(block));
+			continue;
+		}
+		const id = paraIdAttribute(block.element)?.toUpperCase();
+		const replacement = id !== void 0 && changed.has(id) ? fragmentFor(block) : originalXml.slice(original.start, original.end);
+		if (pending.length > 0 || replacement !== originalXml.slice(original.start, original.end)) splices.push({
+			start: original.start,
+			end: original.end,
+			newXml: pending.join("") + replacement
+		});
+		pending = [];
+	}
+	if (pending.length > 0) splices.push({
+		start: source.bodyEnd,
+		end: source.bodyEnd,
+		newXml: pending.join("")
+	});
+	return spliceXml(originalXml, splices);
+};
+//#endregion
+export { buildStructuralDocumentPatch };