@stll/folio-core 0.44.0 → 0.45.0

package/dist/docx/mathToMathml.js

@@ -1,4 +1,5 @@
 import { findChildByLocalName, getLocalName } from "./xmlParser.js";
+import { escapeXmlText } from "@stll/docx-core";
 //#region src/docx/mathToMathml.ts
 /**
 * OMML → MathML conversion.
@@ -95,13 +96,13 @@ const MATH_OPERATOR_HINT = /* @__PURE__ */ new Set([
 	"…"
 ]);
 function renderElement(el) {
-	if (el.type === "text") return escapeXml(textValue(el));
+	if (el.type === "text") return escapeXmlText(textValue(el));
 	if (el.type !== "element") return "";
 	switch (el.name ? getLocalName(el.name) : "") {
 		case "oMath":
 		case "oMathPara": return renderChildren(el);
 		case "r": return renderRun(el);
-		case "t": return escapeXml(extractText(el));
+		case "t": return escapeXmlText(extractText(el));
 		case "f": return renderFraction(el);
 		case "num":
 		case "den": return wrapMrow(renderChildren(el));
@@ -179,8 +180,8 @@ function tokenizeMathText(text) {
 	let bufKind = null;
 	const flush = () => {
 		if (!buf) return;
-		if (bufKind === "digit") out += `<mn>${escapeXml(buf)}</mn>`;
-		else out += `<mi>${escapeXml(buf)}</mi>`;
+		if (bufKind === "digit") out += `<mn>${escapeXmlText(buf)}</mn>`;
+		else out += `<mi>${escapeXmlText(buf)}</mi>`;
 		buf = "";
 		bufKind = null;
 	};
@@ -193,7 +194,7 @@ function tokenizeMathText(text) {
 		const kind = classifyChar(ch);
 		if (kind === "operator") {
 			flush();
-			out += `<mo>${escapeXml(ch)}</mo>`;
+			out += `<mo>${escapeXmlText(ch)}</mo>`;
 			continue;
 		}
 		if (kind === "digit") {
@@ -202,7 +203,7 @@ function tokenizeMathText(text) {
 			continue;
 		}
 		flush();
-		out += `<mi>${escapeXml(ch)}</mi>`;
+		out += `<mi>${escapeXmlText(ch)}</mi>`;
 	}
 	flush();
 	return out;
@@ -258,7 +259,7 @@ function renderNary(el) {
 	const chr = (chrEl ? getAttrValue(chrEl, "val") : null) || "∫";
 	const limLocEl = naryPr ? findChildByLocalName(naryPr, "limLoc") : null;
 	const limLoc = (limLocEl ? getAttrValue(limLocEl, "val") : null) || "subSup";
-	const opMml = `<mo>${escapeXml(chr)}</mo>`;
+	const opMml = `<mo>${escapeXmlText(chr)}</mo>`;
 	const subMml = sub ? wrapMrow(renderChildren(sub)) : "";
 	const supMml = sup ? wrapMrow(renderChildren(sup)) : "";
 	const bodyMml = body ? wrapMrow(renderChildren(body)) : "<mrow/>";
@@ -277,8 +278,8 @@ function renderDelimiter(el) {
 	const begChr = begChrEl ? getAttrValue(begChrEl, "val") ?? "(" : "(";
 	const endChr = endChrEl ? getAttrValue(endChrEl, "val") ?? ")" : ")";
 	const sepChr = sepChrEl ? getAttrValue(sepChrEl, "val") ?? "|" : "|";
-	const inner = (el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "e").map((c) => wrapMrow(renderChildren(c))).join(`<mo>${escapeXml(sepChr)}</mo>`);
-	return `<mrow><mo>${escapeXml(begChr)}</mo>${inner}<mo>${escapeXml(endChr)}</mo></mrow>`;
+	const inner = (el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "e").map((c) => wrapMrow(renderChildren(c))).join(`<mo>${escapeXmlText(sepChr)}</mo>`);
+	return `<mrow><mo>${escapeXmlText(begChr)}</mo>${inner}<mo>${escapeXmlText(endChr)}</mo></mrow>`;
 }
 function renderMatrix(el) {
 	return `<mtable>${(el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "mr").map(renderMatrixRow).join("")}</mtable>`;
@@ -291,7 +292,7 @@ function renderAccent(el) {
 	const chrEl = accPr ? findChildByLocalName(accPr, "chr") : null;
 	const chr = chrEl ? getAttrValue(chrEl, "val") ?? "̂" : "̂";
 	const base = findChildByLocalName(el, "e");
-	return `<mover accent="true">${base ? wrapMrow(renderChildren(base)) : "<mrow/>"}<mo>${escapeXml(chr)}</mo></mover>`;
+	return `<mover accent="true">${base ? wrapMrow(renderChildren(base)) : "<mrow/>"}<mo>${escapeXmlText(chr)}</mo></mover>`;
 }
 function renderBar(el) {
 	const barPr = findChildByLocalName(el, "barPr");
@@ -311,7 +312,7 @@ function renderGroupChr(el) {
 	const chr = chrEl ? getAttrValue(chrEl, "val") ?? defaultChr : defaultChr;
 	const base = findChildByLocalName(el, "e");
 	const baseMml = base ? wrapMrow(renderChildren(base)) : "<mrow/>";
-	const grouper = `<mo stretchy="true">${escapeXml(chr)}</mo>`;
+	const grouper = `<mo stretchy="true">${escapeXmlText(chr)}</mo>`;
 	return pos === "top" ? `<mover>${baseMml}${grouper}</mover>` : `<munder>${baseMml}${grouper}</munder>`;
 }
 function renderLimLow(el) {
@@ -350,8 +351,5 @@ function getAttrValue(el, localAttr) {
 		return String(v);
 	}
 }
-function escapeXml(s) {
-	return s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
-}
 //#endregion
 export { ommlToMathml };

package/dist/docx/nonVisualDrawingProps.d.ts

@@ -0,0 +1,34 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/nonVisualDrawingProps.d.ts
+/** The authored name, alt text and title of a drawing object. */
+type NonVisualDrawingNames = {
+  /** `@name`, schema-required, so `""` means the object was never named. */
+  name?: string;
+  /** `@descr`: alt text, accessibility content. */
+  alt?: string;
+  /** `@title`. */
+  title?: string;
+};
+/**
+ * Read `@name`, `@descr` and `@title` off a `CT_NonVisualDrawingProps` element.
+ *
+ * An attribute that is not there stays absent. `@name` is schema-required, so
+ * an unnamed object still writes one, and `name=""` is the marker the writer
+ * below mints for exactly that: reading it back as an authored name would make
+ * `absent → save → parse` land on `""` instead of absent, and no reader can
+ * tell the two apart. `@descr` and `@title` are optional and written only when
+ * authored, so `""` in either is a string someone wrote.
+ */
+declare const parseNonVisualDrawingNames: (element: XmlElement | null | undefined) => NonVisualDrawingNames;
+/**
+ * The `name`, `descr` and `title` attributes of a `CT_NonVisualDrawingProps`
+ * element, leading space included.
+ *
+ * `@name` is schema-required, so an object carrying none writes the empty
+ * string. folio does not name an object it did not author: a generated
+ * "Shape 3" would overwrite the author's own name for every drawing whose
+ * name did not survive the model, and read back as authored content.
+ */
+declare const serializeNonVisualDrawingNames: (names: NonVisualDrawingNames) => string;
+//#endregion
+export { NonVisualDrawingNames, parseNonVisualDrawingNames, serializeNonVisualDrawingNames };

package/dist/docx/nonVisualDrawingProps.js

@@ -0,0 +1,46 @@
+import { getAttribute } from "./xmlParser.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
+//#region src/docx/nonVisualDrawingProps.ts
+/**
+* `CT_NonVisualDrawingProps` (`wp:docPr`, `wps:cNvPr`, `pic:cNvPr`) carries the
+* three authored strings every drawing object has: its name, its alt text
+* (`descr`) and its title. They are authored content, not folio's to mint, so
+* one reader and one writer own them for every drawing kind.
+*/
+/**
+* Read `@name`, `@descr` and `@title` off a `CT_NonVisualDrawingProps` element.
+*
+* An attribute that is not there stays absent. `@name` is schema-required, so
+* an unnamed object still writes one, and `name=""` is the marker the writer
+* below mints for exactly that: reading it back as an authored name would make
+* `absent → save → parse` land on `""` instead of absent, and no reader can
+* tell the two apart. `@descr` and `@title` are optional and written only when
+* authored, so `""` in either is a string someone wrote.
+*/
+const parseNonVisualDrawingNames = (element) => {
+	if (!element) return {};
+	const name = getAttribute(element, null, "name");
+	const descr = getAttribute(element, null, "descr");
+	const title = getAttribute(element, null, "title");
+	return {
+		...name !== null && name !== "" ? { name } : {},
+		...descr !== null ? { alt: descr } : {},
+		...title !== null ? { title } : {}
+	};
+};
+/**
+* The `name`, `descr` and `title` attributes of a `CT_NonVisualDrawingProps`
+* element, leading space included.
+*
+* `@name` is schema-required, so an object carrying none writes the empty
+* string. folio does not name an object it did not author: a generated
+* "Shape 3" would overwrite the author's own name for every drawing whose
+* name did not survive the model, and read back as authored content.
+*/
+const serializeNonVisualDrawingNames = (names) => {
+	const descr = names.alt === void 0 ? "" : ` descr="${escapeXmlAttribute(names.alt)}"`;
+	const title = names.title === void 0 ? "" : ` title="${escapeXmlAttribute(names.title)}"`;
+	return ` name="${escapeXmlAttribute(names.name ?? "")}"${descr}${title}`;
+};
+//#endregion
+export { parseNonVisualDrawingNames, serializeNonVisualDrawingNames };

package/dist/docx/paragraphTextBoxEnrichment.js

@@ -198,6 +198,9 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 				type: "shape",
 				shapeType: "textBox",
 				size: textBox.size,
+				...textBox.name !== void 0 ? { name: textBox.name } : {},
+				...textBox.alt !== void 0 ? { alt: textBox.alt } : {},
+				...textBox.title !== void 0 ? { title: textBox.title } : {},
 				...textBox.position !== void 0 ? { position: textBox.position } : {},
 				...textBox.wrap !== void 0 ? { wrap: textBox.wrap } : {},
 				...textBox.fill !== void 0 ? { fill: textBox.fill } : {},

package/dist/docx/parser.js

@@ -23,6 +23,7 @@ import { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumber
 import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
 import { createParseWarningCollector } from "./parseContext.js";
 import { formatParseWarnings } from "./parseWarningMessage.js";
+import { enforcePackagePreviewBudget } from "./previewBudget.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRenderedPageBreakHints } from "./renderedPageBreakNormalization.js";
 import { parseSettings } from "./settingsParser.js";
@@ -30,7 +31,6 @@ import { parseStylesPackage } from "./styleParser.js";
 import { applyThemeFontLang, parseTheme } from "./themeParser.js";
 import { UNBALANCED_MOVE_RANGE_WARNING, normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
 import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
-import { enforcePackageVmlPreviewBudget } from "./vmlPreview.js";
 import { FOLIO_XML_RESOURCE_LIMITS } from "./xmlResourceLimits.js";
 import { TaggedError } from "better-result";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
@@ -281,7 +281,7 @@ async function parseDocx(input, options = {}) {
 			...requiredFonts.length > 0 ? { requiredFonts } : {}
 		};
 		assignDocumentParagraphPropertySourceContract(document, await paragraphPropertySourceDigest);
-		enforcePackageVmlPreviewBudget(document.package);
+		enforcePackagePreviewBudget(document.package);
 		const validation = validateFolioDocumentModel(document);
 		const parsedCompleteModel = parseHeadersFooters && parseNotes;
 		if (!validation.valid && parsedCompleteModel) throw new DocxModelValidationError("Parsed DOCX produced an invalid document model", validation.issues);

package/dist/docx/previewBudget.d.ts

@@ -0,0 +1,64 @@
+//#region src/docx/previewBudget.d.ts
+/**
+ * Every synthetic preview a parse attaches to the model, and the budget each
+ * one answers to.
+ *
+ * A preview is not document content. It is a drawing folio makes up so a shape
+ * it cannot project still occupies the page, and the package round-trips from
+ * its preserved XML whether the preview exists or not. So a preview is the one
+ * thing in the model that may be dropped, and a package that would retain more
+ * of it than it is worth has it dropped rather than being refused.
+ *
+ * Producer and budget have to agree on what a preview looks like. They used to
+ * agree by coincidence: the VML producer wrote its filename as a literal and
+ * the budget recognized it as a constant in another file, so renaming one
+ * would have stopped the other charging for it without anything failing. The
+ * table below is that agreement written once, and a producer builds its image
+ * out of the entry the budget matches against.
+ */
+declare const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
+declare const PREVIEW_KINDS: {
+  /** A VML shape folio renders rather than projects (`v:shape`, `v:rect`, ...). */
+  readonly vmlShape: {
+    readonly mimeType: "image/svg+xml";
+    readonly filename: "vml-shape-preview.svg";
+    readonly srcPrefix: "data:image/svg+xml;charset=utf-8,";
+    readonly maxPackageCharacters: number;
+  };
+  /**
+   * A SmartArt diagram: its extent filled with one flat rectangle per shape.
+   *
+   * A raster rather than a vector because the display list decodes only base64
+   * PNG and JPEG, so a vector preview would be missing from every display-list
+   * backend (PDF among them) while still showing in the DOM. That is what
+   * makes this preview expensive: one of them is 7.3 MB of data URL whatever
+   * the package weighs, because its cost follows the extent the author chose
+   * rather than anything the drawing contains.
+   *
+   * Across the public corpus, the fifty packages that produce one retain a
+   * median of 7.3 MB and a maximum of 51.3 MB (ten previews, from a package
+   * under a megabyte). The cap is set above that maximum: it refuses no
+   * legitimate file in the corpus while bounding what had no bound at all, and
+   * it is a ceiling rather than a fix. The fix is for the preview to be a
+   * descriptor the renderer rasterizes, which needs the display-list contract
+   * to carry one.
+   */
+  readonly smartArt: {
+    readonly mimeType: "image/png";
+    readonly filename: "smartart-preview.png";
+    readonly srcPrefix: "data:image/png;base64,";
+    readonly maxPackageCharacters: number;
+  };
+};
+type PreviewKindName = keyof typeof PREVIEW_KINDS;
+/** Per-kind allowances for one package, defaulting to the table's caps. */
+type PreviewBudgetOverrides = Partial<Record<PreviewKindName, number>>;
+/**
+ * Charge every generated preview in the model against its kind's allowance and
+ * drop the `src` of those past it. Dropping leaves the image in place with its
+ * size and wrap, so the page still reserves the space the drawing occupies,
+ * and never touches the preserved XML the package saves from.
+ */
+declare const enforcePackagePreviewBudget: (root: unknown, overrides?: PreviewBudgetOverrides) => void;
+//#endregion
+export { PREVIEW_KINDS, PreviewBudgetOverrides, VML_PREVIEW_DATA_URL_PREFIX, enforcePackagePreviewBudget };

package/dist/docx/previewBudget.js

@@ -0,0 +1,88 @@
+//#region src/docx/previewBudget.ts
+const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
+const MEBIBYTE = 1024 * 1024;
+const PREVIEW_KINDS = {
+	/** A VML shape folio renders rather than projects (`v:shape`, `v:rect`, ...). */
+	vmlShape: {
+		mimeType: "image/svg+xml",
+		filename: "vml-shape-preview.svg",
+		srcPrefix: VML_PREVIEW_DATA_URL_PREFIX,
+		maxPackageCharacters: 8 * MEBIBYTE
+	},
+	/**
+	* A SmartArt diagram: its extent filled with one flat rectangle per shape.
+	*
+	* A raster rather than a vector because the display list decodes only base64
+	* PNG and JPEG, so a vector preview would be missing from every display-list
+	* backend (PDF among them) while still showing in the DOM. That is what
+	* makes this preview expensive: one of them is 7.3 MB of data URL whatever
+	* the package weighs, because its cost follows the extent the author chose
+	* rather than anything the drawing contains.
+	*
+	* Across the public corpus, the fifty packages that produce one retain a
+	* median of 7.3 MB and a maximum of 51.3 MB (ten previews, from a package
+	* under a megabyte). The cap is set above that maximum: it refuses no
+	* legitimate file in the corpus while bounding what had no bound at all, and
+	* it is a ceiling rather than a fix. The fix is for the preview to be a
+	* descriptor the renderer rasterizes, which needs the display-list contract
+	* to carry one.
+	*/
+	smartArt: {
+		mimeType: "image/png",
+		filename: "smartart-preview.png",
+		srcPrefix: "data:image/png;base64,",
+		maxPackageCharacters: 64 * MEBIBYTE
+	}
+};
+const KIND_NAMES = Object.keys(PREVIEW_KINDS);
+/**
+* The kind a model image was generated as, or `undefined` for one the package
+* actually carries. A generated preview has no relationship behind it, so
+* `rId` is empty; the filename and data-URL prefix name which producer made it.
+*/
+const previewKindOf = (value) => {
+	if (!("type" in value) || value.type !== "image" || !("rId" in value) || value.rId !== "" || !("src" in value) || typeof value.src !== "string" || !("mimeType" in value) || !("filename" in value)) return;
+	const { src, mimeType, filename } = value;
+	return KIND_NAMES.find((name) => {
+		const kind = PREVIEW_KINDS[name];
+		return mimeType === kind.mimeType && filename === kind.filename && src.startsWith(kind.srcPrefix);
+	});
+};
+/**
+* Charge every generated preview in the model against its kind's allowance and
+* drop the `src` of those past it. Dropping leaves the image in place with its
+* size and wrap, so the page still reserves the space the drawing occupies,
+* and never touches the preserved XML the package saves from.
+*/
+const enforcePackagePreviewBudget = (root, overrides = {}) => {
+	const remaining = new Map(KIND_NAMES.map((name) => [name, Math.max(0, overrides[name] ?? PREVIEW_KINDS[name].maxPackageCharacters)]));
+	const visited = /* @__PURE__ */ new WeakSet();
+	const visit = (value) => {
+		if (value === null || typeof value !== "object" || visited.has(value)) return;
+		visited.add(value);
+		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return;
+		if (value instanceof Map) {
+			for (const child of value.values()) visit(child);
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const child of value) visit(child);
+			return;
+		}
+		const kind = previewKindOf(value);
+		if (kind !== void 0) {
+			const image = value;
+			const length = image.src.length;
+			const left = remaining.get(kind);
+			if (length <= left) remaining.set(kind, left - length);
+			else {
+				remaining.set(kind, 0);
+				delete image.src;
+			}
+		}
+		for (const child of Object.values(value)) visit(child);
+	};
+	visit(root);
+};
+//#endregion
+export { PREVIEW_KINDS, VML_PREVIEW_DATA_URL_PREFIX, enforcePackagePreviewBudget };

package/dist/docx/revisionIdNormalization.js

@@ -117,7 +117,10 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	const occurrencesByPath = /* @__PURE__ */ new Map();
 	const reserved = /* @__PURE__ */ new Set();
 	for (const [path, xml] of candidates) {
-		assertXmlResourceLimits(xml);
+		assertXmlResourceLimits({
+			xml,
+			partPath: path
+		});
 		const ids = [];
 		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
 			const identified = identifiedElement(element);
@@ -127,7 +130,9 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 			return null;
 		}).status === "unsupported") throw new XmlResourceLimitError({
 			message: `Revision-id normalization could not safely scan ${path}`,
-			limit: "syntax"
+			limit: "syntax",
+			observed: 0,
+			allowed: 0
 		});
 		occurrencesByPath.set(path, ids);
 	}
@@ -137,14 +142,19 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	else firstSeen.add(id);
 	if (repeatedPaths.size > 0) for (const [path, xml] of parts) {
 		if (occurrencesByPath.has(path) || !ANNOTATION_ELEMENT_CANDIDATE.test(xml)) continue;
-		assertXmlResourceLimits(xml);
+		assertXmlResourceLimits({
+			xml,
+			partPath: path
+		});
 		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
 			const identified = identifiedElement(element);
 			if (identified !== null) reserved.add(identified.id);
 			return null;
 		}).status === "unsupported") throw new XmlResourceLimitError({
 			message: `Revision-id normalization could not safely scan ${path}`,
-			limit: "syntax"
+			limit: "syntax",
+			observed: 0,
+			allowed: 0
 		});
 	}
 	let nextId = 0;
@@ -185,7 +195,9 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 		});
 		if (rewritten.status === "unsupported") throw new XmlResourceLimitError({
 			message: `Revision-id normalization could not safely rewrite ${path}`,
-			limit: "syntax"
+			limit: "syntax",
+			observed: 0,
+			allowed: 0
 		});
 		normalized.set(path, rewritten.value);
 	}

package/dist/docx/rezip.js

@@ -19,7 +19,7 @@ import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./r
 import { removeResolvedHeaderFooterParts } from "./removeHeaderFooterParts.js";
 import { normalizeRevisionIdsInXmlParts } from "./revisionIdNormalization.js";
 import { buildPatchedNotePartXml, collectChangedNoteParaIds, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
-import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
+import { planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeFontTableXml } from "./serializer/fontTableSerializer.js";
 import { serializeHeaderFooter } from "./serializer/headerFooterSerializer.js";
@@ -29,11 +29,10 @@ import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
-import { escapeXml } from "./serializer/xmlUtils.js";
 import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
 import { panic } from "better-result";
-import { validateDocxPackage } from "@stll/docx-core";
+import { escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
 import JSZip from "jszip";
 //#region src/docx/rezip.ts
 /**
@@ -85,7 +84,7 @@ function findMaxRId(relsXml) {
 }
 const isWordprocessingElement = (element, localName) => getLocalName(element.name) === localName && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "");
 const countDocumentSections = (xml) => {
-	assertXmlResourceLimits(xml);
+	assertXmlResourceLimits({ xml });
 	let count = 0;
 	const pending = [{
 		element: parseXml(xml),
@@ -106,7 +105,7 @@ const countDocumentSections = (xml) => {
 };
 const extractHeaderFooterReferences = (xml) => {
 	const references = [];
-	assertXmlResourceLimits(xml);
+	assertXmlResourceLimits({ xml });
 	const pending = [parseXml(xml)];
 	while (pending.length > 0) {
 		const node = pending.pop();
@@ -166,15 +165,15 @@ async function serializeCommentsToZip(doc, zip, compressionLevel) {
 	if (comments.length === 0) {
 		if (sourceCommentsXml === void 0 || !hasCommentEntries(sourceCommentsXml)) return;
 	}
-	ensureThreadedCommentParaIds(comments);
-	const commentsXml = serializeComments(comments, sourceCommentsXml === void 0 ? void 0 : readRootNamespaceBindings(sourceCommentsXml));
+	const plan = planCommentParts(comments);
+	const commentsXml = serializeComments(plan, sourceCommentsXml === void 0 ? void 0 : readRootNamespaceBindings(sourceCommentsXml));
 	zip.file(sourceCommentsFile?.name ?? "word/comments.xml", commentsXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
 	await ensureCommentsContentType(zip, compressionLevel);
 	await ensureCommentsRelationship(zip, compressionLevel);
-	await syncCommentsExtendedPart(comments, zip, compressionLevel);
+	await syncCommentsExtendedPart(plan, zip, compressionLevel);
 }
 const hasCommentEntries = (xml) => {
 	const root = parseXml(xml);
@@ -189,8 +188,8 @@ const hasCommentEntries = (xml) => {
 * 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);
+async function syncCommentsExtendedPart(plan, zip, compressionLevel) {
+	const xml = serializeCommentsExtended(plan);
 	const existing = findZipEntryCaseInsensitive(zip, COMMENTS_EXTENDED_PART_LOWER);
 	if (!xml) {
 		if (!existing) return;
@@ -396,7 +395,7 @@ async function processNewImages(parts, zip, compressionLevel) {
 				compression: "DEFLATE",
 				compressionOptions: { level: compressionLevel }
 			});
-			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXml(relativeTargetForPart(partPath, mediaPath))}"/>`);
+			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXmlAttribute(relativeTargetForPart(partPath, mediaPath))}"/>`);
 			extensionsAdded.add(extension);
 			if (drawing.rawXml) drawing.rawXml = rebindDrawingImageRelationship({
 				xml: drawing.rawXml,
@@ -476,7 +475,7 @@ async function processNewHyperlinks(parts, zip, compressionLevel) {
 			if (!hyperlink.href) continue;
 			maxId++;
 			const newRId = `rId${maxId}`;
-			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.hyperlink}" Target="${escapeXml(hyperlink.href)}" TargetMode="External"/>`);
+			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.hyperlink}" Target="${escapeXmlAttribute(hyperlink.href)}" TargetMode="External"/>`);
 			hyperlink.rId = newRId;
 		}
 		zip.file(relsPath, relsXml.replace("</Relationships>", `${relEntries.join("")}</Relationships>`), {
@@ -952,7 +951,7 @@ async function addRelationship(originalBuffer, relationship) {
 	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 newRelElement = `<Relationship Id="${newRId}" Type="${relationship.type}" Target="${escapeXmlAttribute(relationship.target)}"${targetModeAttr}/>`;
 	const updatedRelsXml = relsXml.replace("</Relationships>", `${newRelElement}</Relationships>`);
 	zip.file(relsPath, updatedRelsXml);
 	return {
@@ -1101,7 +1100,7 @@ async function materializeNewHeaderFooterParts(doc, zip, compressionLevel) {
 				type: relType,
 				target: filename
 			});
-			relEntries.push(`<Relationship Id="${escapeXml(effectiveRId)}" Type="${relType}" Target="${filename}"/>`);
+			relEntries.push(`<Relationship Id="${escapeXmlAttribute(effectiveRId)}" Type="${relType}" Target="${filename}"/>`);
 			overrides.push(`<Override PartName="/word/${filename}" ContentType="${contentType}"/>`);
 		}
 	};
@@ -1218,7 +1217,7 @@ async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 		}
 		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))}"/>`;
+			const relXml = canonical.mode === "external" ? `<Relationship Id="${resolvedRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXmlAttribute(canonical.url)}" TargetMode="External"/>` : `<Relationship Id="${resolvedRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXmlAttribute(relativeTargetForPart(partPath, canonical.absolute))}"/>`;
 			relsXmlByPath.set(relsPath, relsXml.replace("</Relationships>", `${relXml}</Relationships>`));
 			changedPaths.add(relsPath);
 		}
@@ -1531,7 +1530,7 @@ function updateCoreProperties(corePropsXml, { updateModifiedDate, modifiedBy })
 		if (result.includes("<dcterms:modified")) result = result.replace(/<dcterms:modified[^<>]*>[^<]*<\/dcterms:modified>/u, `<dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified>`);
 	}
 	if (modifiedBy) {
-		if (result.includes("<cp:lastModifiedBy")) result = result.replace(/<cp:lastModifiedBy>[^<]*<\/cp:lastModifiedBy>/u, `<cp:lastModifiedBy>${escapeXml(modifiedBy)}</cp:lastModifiedBy>`);
+		if (result.includes("<cp:lastModifiedBy")) result = result.replace(/<cp:lastModifiedBy>[^<]*<\/cp:lastModifiedBy>/u, `<cp:lastModifiedBy>${escapeXmlText(modifiedBy)}</cp:lastModifiedBy>`);
 	}
 	return result;
 }
@@ -1638,13 +1637,13 @@ const createEmptyDocxZip = ({ creator, application }) => {
 </w:document>`);
 	zip.file(STYLES_PART_PATH, SEED_STYLES_XML);
 	const now = (/* @__PURE__ */ new Date()).toISOString();
-	const creatorElement = creator === void 0 ? "" : `\n  <dc:creator>${escapeXml(creator)}</dc:creator>`;
+	const creatorElement = creator === void 0 ? "" : `\n  <dc:creator>${escapeXmlText(creator)}</dc:creator>`;
 	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">${creatorElement}
   <dcterms:created xsi:type="dcterms:W3CDTF">${now}</dcterms:created>
   <dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified>
 </cp:coreProperties>`);
-	const applicationElements = application === void 0 ? "" : `\n  <Application>${escapeXml(application)}</Application>\n  <AppVersion>${CREATED_APP_VERSION}</AppVersion>`;
+	const applicationElements = application === void 0 ? "" : `\n  <Application>${escapeXmlText(application)}</Application>\n  <AppVersion>${CREATED_APP_VERSION}</AppVersion>`;
 	zip.file("docProps/app.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties">${applicationElements}
 </Properties>`);

package/dist/docx/sdtPropertiesPatch.js

@@ -1,21 +1,27 @@
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/sdtPropertiesPatch.ts
-const XML_ATTR_ESCAPES = {
-	"&": "&",
-	"<": "&lt;",
-	">": "&gt;",
-	"\"": "&quot;",
-	"'": "&apos;"
-};
 /**
-* Escape a value for embedding in an XML attribute. Single-pass replace
-* over the five XML metacharacters (incl. apostrophe so the function
-* stays correct for `'`-delimited attributes even though this file always
-* emits double-quoted ones). Output is XML written to a DOCX zip — no
-* HTML / browser interpretation downstream.
+* Surgical patches for the captured `<w:sdtPr>` XML string.
+*
+* Background. The block-SDT serializer (commit 3) replays
+* `properties.rawPropertiesXml` verbatim so unmodeled OOXML markers
+* (`w:dataBinding`, `w15:repeatingSection`, custom XML mappings) survive
+* a round trip. That replay is correct for unchanged controls but goes
+* stale the moment the editor mutates a modeled property: a user
+* toggling a checkbox, picking a date, or choosing a dropdown value
+* updates `properties.checked` / `dateFormat` / etc., but the raw
+* `w14:checked w14:val="0"` already encoded by the source DOCX stays
+* in `rawPropertiesXml` and gets written back on save — Word reopens
+* the document with the user's interactive change discarded.
+*
+* `reconcileRawSdtPr` walks every modeled field that has an OOXML
+* representation inside `<w:sdtPr>` and, if the field is set on the
+* model, rewrites the matching element in the raw string. Unmodeled
+* markers are untouched, so dataBinding / repeatingSection round-trip
+* stays lossless even after the user has mutated the control.
+*
+* Picked up from upstream eigenpal/docx-editor#661.
 */
-function escapeXmlAttr(value) {
-	return value.replace(/[&<>"']/gu, (ch) => XML_ATTR_ESCAPES[ch] ?? ch);
-}
 /**
 * Drop any `*:lastValue="…"` attribute (any namespace prefix, or
 * unprefixed) from an attribute-list string. We avoid a single greedy
@@ -116,8 +122,8 @@ function reconcileRawSdtPr(raw, props, options = {}) {
 		if (fullDate !== void 0 || dateFormat !== void 0) {
 			const wDate = /<(?<prefix>\w+):date\b(?<attrs>[^>]*)>(?<inner>[\s\S]*?)<\/\w+:date>/iu;
 			const wDateSelf = /<(?<prefix>\w+):date\b(?<attrs>[^/>]*)\/>/iu;
-			const fullDateAttr = fullDate !== void 0 ? ` w:fullDate="${escapeXmlAttr(fullDate)}"` : "";
-			const formatChild = dateFormat !== void 0 ? `<w:dateFormat w:val="${escapeXmlAttr(dateFormat)}"/>` : "";
+			const fullDateAttr = fullDate !== void 0 ? ` w:fullDate="${escapeXmlAttribute(fullDate)}"` : "";
+			const formatChild = dateFormat !== void 0 ? `<w:dateFormat w:val="${escapeXmlAttribute(dateFormat)}"/>` : "";
 			if (wDate.test(next)) next = next.replace(wDate, (_match, prefix, matchedAttrs, inner) => {
 				let body = inner.replaceAll(/<\w+:dateFormat\b[^>]*(?:\/>|>[\s\S]*?<\/\w+:dateFormat>)/giu, "");
 				if (formatChild) body = `${formatChild}${body}`;
@@ -128,7 +134,7 @@ function reconcileRawSdtPr(raw, props, options = {}) {
 		}
 	}
 	if ((props.sdtType === "dropdown" || props.sdtType === "comboBox") && options.dropdownLastValue !== void 0) {
-		const escapedValue = escapeXmlAttr(options.dropdownLastValue);
+		const escapedValue = escapeXmlAttribute(options.dropdownLastValue);
 		const opened = /<(?<prefix>\w+):(?<name>dropDownList|comboBox)\b(?<attrs>[^>]*)>(?<inner>[\s\S]*?)<\/\w+:(?:dropDownList|comboBox)>/iu;
 		const selfClosing = /<(?<prefix>\w+):(?<name>dropDownList|comboBox)\b(?<attrs>[^/>]*)\/>/iu;
 		if (opened.test(next)) next = next.replace(opened, (_match, prefix, name, attrs, inner) => {

package/dist/docx/sectionReferenceHistory.js

@@ -1,7 +1,7 @@
 import { canonicalJson } from "../utils/canonicalJson.js";
-import { escapeXml } from "./serializer/xmlUtils.js";
 import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChildrenByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri } from "./xmlParser.js";
 import { TaggedError } from "better-result";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/sectionReferenceHistory.ts
 const SECTION_REFERENCE_HISTORY_NAMESPACE = "urn:stella:folio:section-reference-history:1";
 const HISTORY_NAMESPACES = /* @__PURE__ */ new Set([SECTION_REFERENCE_HISTORY_NAMESPACE]);
@@ -41,7 +41,7 @@ const serializeSectionReferenceHistory = (references) => {
 		if (new Set(values.map(({ type }) => type)).size !== values.length) return invalidHistory();
 		return values.map(({ type, rId }) => {
 			if (!rId || rId.trim() !== rId) return invalidHistory();
-			return `<w:${kind}Reference w:type="${type}" r:id="${escapeXml(rId)}"/>`;
+			return `<w:${kind}Reference w:type="${type}" r:id="${escapeXmlAttribute(rId)}"/>`;
 		}).join("");
 	};
 	const content = serializeReferences("header", references.headerReferences ?? []) + serializeReferences("footer", references.footerReferences ?? []);