@stll/folio-core 0.44.0 → 0.46.0

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 { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, 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,
@@ -444,6 +443,7 @@ function collectHyperlinksWithoutRId(blocks) {
 				break;
 			case "simpleField":
 			case "inlineSdt":
+			case "inlineWrapper":
 			case "insertion":
 			case "deletion":
 			case "moveFrom":
@@ -455,7 +455,7 @@ function collectHyperlinksWithoutRId(blocks) {
 	};
 	for (const block of blocks) if (block.type === "paragraph") collectInlineHyperlinks(block.content);
 	else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) hyperlinks.push(...collectHyperlinksWithoutRId(cell.content));
-	else hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
+	else if (block.type === "blockSdt") hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
 	return hyperlinks;
 }
 /** The selective save boundary must use the same resource census as full repack. */
@@ -476,7 +476,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 +952,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 +1101,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 +1218,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);
 		}
@@ -1426,7 +1426,26 @@ const seedStylesXmlWith = (missing) => {
 	const rootClose = SEED_STYLES_XML.lastIndexOf(STYLES_CLOSE_ROOT);
 	return SEED_STYLES_XML.slice(0, rootClose) + missing.map(serializeStyle).join("") + SEED_STYLES_XML.slice(rootClose);
 };
-const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
+/**
+* The style ids `word/styles.xml` already defines.
+*
+* Read by parsing the part, because the model holds the *decoded* id and the
+* part holds its XML spelling: `w:styleId='Body A'` is single-quoted,
+* `w:styleId="Header &amp; Footer"` is escaped, and either may sit behind an
+* attribute value containing `>`. A reader that misses one of those reports a
+* style the part already defines as missing, and
+* {@link serializeAddedStylesIntoZip} appends it — on every save, for ever.
+*/
+const definedStyleIds = (stylesXml) => {
+	const root = parseXml(stylesXml);
+	const styles = findChildByNamespaceUri(root, WORDPROCESSINGML_NAMESPACE_URIS, "styles") ?? root;
+	const ids = /* @__PURE__ */ new Set();
+	for (const style of findChildrenByNamespaceUri(styles, WORDPROCESSINGML_NAMESPACE_URIS, "style")) {
+		const id = getAttributeByNamespaceUri(style, WORDPROCESSINGML_NAMESPACE_URIS, "styleId") ?? style.attributes?.["w:styleId"];
+		if (id !== void 0 && id !== null && id !== "") ids.add(String(id));
+	}
+	return ids;
+};
 /**
 * Append styles the model defines but the original `word/styles.xml` lacks.
 * Existing styles stay byte-exact (edits to them are not written here, the
@@ -1472,9 +1491,13 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		});
 		return;
 	}
-	const existing = /* @__PURE__ */ new Set();
-	for (const match of originalXml.matchAll(STYLE_ID_PATTERN)) existing.add(match.groups["id"]);
-	const added = styles.styles.filter((style) => !existing.has(style.styleId));
+	const existing = new Set(definedStyleIds(originalXml));
+	const added = [];
+	for (const style of styles.styles) {
+		if (existing.has(style.styleId)) continue;
+		existing.add(style.styleId);
+		added.push(style);
+	}
 	if (added.length === 0) return;
 	const patched = originalXml.slice(0, rootClose) + added.map(serializeStyle).join("") + originalXml.slice(rootClose);
 	newZip.file(file.name, patched, {
@@ -1482,28 +1505,60 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		compressionOptions: { level: compressionLevel }
 	});
 }
+/**
+* The XML to write for a patched note part, or null to keep the original.
+*
+* A refusal over comment-range balance is not a failure to serialize: the
+* splice was too narrow to keep a comment's range whole, so the part is
+* written from the model, which is balanced with itself and with the
+* `document.xml` this repack rewrites beside it. Word's required separator
+* notes come back synthesized rather than byte-exact, the price of keeping the
+* comment anchored to the text it was written about. Any other refusal means a
+* changed paragraph could not be located in the part at all, which no wider
+* rewrite fixes.
+*/
+const notePartXmlFor = ({ patch, originalXml, replacementXml, hasDirtyParagraph, elementName, partName }) => {
+	const keepOriginal = () => {
+		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${partName}`);
+		return null;
+	};
+	switch (patch.type) {
+		case "patched": return patch.xml === originalXml ? keepOriginal() : patch.xml;
+		case "refused": switch (patch.reason) {
+			case "comment-range-balance": return replacementXml;
+			case "unroutable-paragraph": return keepOriginal();
+			default: {
+				const unreachable = patch.reason;
+				return panic("Unhandled note-part patch refusal", { reason: unreachable });
+			}
+		}
+		default: return panic("Unhandled note-part patch", { patch });
+	}
+};
 async function patchNotePartIntoZip({ conventionalLowerPath, currentXml, replacementXml, baselineFrom, elementName, changedNoteParaIds, originalZip, newZip, compressionLevel }) {
 	const file = findNotePartEntry(originalZip, conventionalLowerPath);
 	if (!file) return;
 	const originalXml = await file.async("text");
 	const baselineXml = baselineFrom(originalXml);
 	const effectiveChangedNoteParaIds = changedNoteParaIds ?? collectChangedNoteParaIds(baselineXml, currentXml);
-	const patched = buildPatchedNotePartXml({
+	const currentParaIds = collectParaIds(currentXml);
+	const patchedXml = notePartXmlFor({
+		patch: buildPatchedNotePartXml({
+			originalXml,
+			baselineXml,
+			serializedXml: currentXml,
+			replacementXml,
+			elementName,
+			changedParaIds: effectiveChangedNoteParaIds
+		}),
 		originalXml,
-		baselineXml,
-		serializedXml: currentXml,
 		replacementXml,
+		hasDirtyParagraph: [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId)),
 		elementName,
-		changedParaIds: effectiveChangedNoteParaIds
+		partName: file.name
 	});
-	const currentParaIds = collectParaIds(currentXml);
-	const hasDirtyParagraph = [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId));
-	if (patched === null || hasDirtyParagraph && patched === originalXml) {
-		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${file.name}`);
-		return;
-	}
-	if (patched === originalXml) return;
-	newZip.file(file.name, patched, {
+	if (patchedXml === null || patchedXml === originalXml) return;
+	newZip.file(file.name, patchedXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
@@ -1531,7 +1586,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 +1693,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/runParser.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/runParser.d.ts
 /**
  * `w:vertAlign` `baseline` is the reserved value that means "no vertical

package/dist/docx/runParser.js

@@ -1,9 +1,12 @@
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseDiagramPreview } from "./diagramPreview.js";
+import { parseFieldState } from "./fieldState.js";
 import { isGroupDrawing, parseGroupDrawing } from "./groupDrawingParser.js";
 import { parseImage } from "./imageParser.js";
 import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { preserveRunChild } from "./preservedRunContent.js";
 import { parseShading } from "./shadingParser.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
@@ -11,7 +14,7 @@ import { resolveThemeFontRef } from "./themeParser.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { parseVmlImageContent, shouldPreserveRawVmlPict } from "./vmlImageParser.js";
-import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, selectAlternateContentBranch } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
@@ -419,17 +422,14 @@ function parseEndnoteReference(element) {
 */
 function parseFieldChar(element) {
 	const fldCharType = getAttribute(element, "w", "fldCharType");
-	const fldLock = parseOnOffAttribute(element, "w", "fldLock") === true;
-	const dirty = parseOnOffAttribute(element, "w", "dirty") === true;
 	let charType = "begin";
 	if (fldCharType === "separate") charType = "separate";
 	else if (fldCharType === "end") charType = "end";
 	const content = {
 		type: "fieldChar",
-		charType
+		charType,
+		...parseFieldState(element)
 	};
-	if (fldLock) content.fldLock = true;
-	if (dirty) content.dirty = true;
 	const numberingChange = findChild(element, "w", "numberingChange");
 	if (numberingChange) {
 		const original = getAttribute(numberingChange, "w", "original");
@@ -576,10 +576,11 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 		}
 		case "object": {
 			const objectPreview = parseVmlImageContent(child, rels, media, rootXmlns);
-			if (objectPreview) contents.push(objectPreview);
+			contents.push(objectPreview ?? preserveRunChild(child));
 			break;
 		}
 		case "rPr": break;
+		case "commentReference": break;
 		case "lastRenderedPageBreak":
 			contents.push({ type: "renderedPageBreak" });
 			break;
@@ -637,11 +638,9 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 			if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
 			break;
 		}
-		case "footnoteRef":
-		case "endnoteRef": break;
-		case "separator":
-		case "continuationSeparator": break;
-		default: break;
+		default:
+			contents.push(preserveRunChild(child));
+			break;
 	}
 	return contents;
 }
@@ -668,6 +667,11 @@ function parseRun(node, styles, theme, rels = null, media = null, rootXmlns = {}
 		if (propertyChangesResult) run.propertyChanges = propertyChangesResult;
 	}
 	run.content = parseRunContents(node, rels, media, mergeXmlnsDeclarations(rootXmlns, node));
+	const remainder = attributeRemainder({
+		element: node,
+		modelled: NO_MODELLED_ATTRIBUTES
+	});
+	if (remainder) run.preservedAttributes = remainder;
 	return run;
 }
 /**

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/sectionParser.js

@@ -1,3 +1,4 @@
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseBorderSpec } from "./borderParser.js";
 import { parseFooterReference, parseHeaderReference } from "./headerFooterRefParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
@@ -159,7 +160,8 @@ function parseSectionProperties(sectPr, context) {
 		if (space !== void 0) props.columnSpace = space;
 		const equalWidth = parseOnOffAttribute(cols, "w", "equalWidth");
 		if (equalWidth !== void 0) props.equalWidth = equalWidth;
-		if (parseOnOffAttribute(cols, "w", "sep") === true) props.separator = true;
+		const separator = parseOnOffAttribute(cols, "w", "sep");
+		if (separator !== void 0) props.separator = separator;
 		const colElements = findChildren(cols, "w", "col");
 		if (colElements.length > 0) {
 			props.columns = [];
@@ -310,6 +312,11 @@ function parseSectionProperties(sectPr, context) {
 		return change;
 	});
 	if (propertyChanges.length > 0) props.propertyChanges = propertyChanges;
+	const remainder = attributeRemainder({
+		element: sectPr,
+		modelled: NO_MODELLED_ATTRIBUTES
+	});
+	if (remainder) props.preservedAttributes = remainder;
 	Object.defineProperty(props, unserializedSectionPropertyChildNames, {
 		enumerable: true,
 		value: unhandledChildNames

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 ?? []);

package/dist/docx/selectiveSave.js

@@ -8,7 +8,7 @@ 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 { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.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";
@@ -84,8 +84,8 @@ const commentsExtendedInfoEqual = (a, b) => {
 * - 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);
+async function patchCommentsExtended(zip, plan, updates) {
+	const desiredXml = serializeCommentsExtended(plan);
 	const existing = findZipEntryCaseInsensitive(zip, COMMENTS_EXTENDED_PART_LOWER);
 	if (!desiredXml) return existing === null;
 	const baselineInfo = existing ? parseCommentsExtended(await existing.async("text")) : /* @__PURE__ */ new Map();
@@ -190,6 +190,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	if (!validateFolioDocumentModel(doc).valid) return null;
 	const comments = doc.package.document.comments ?? [];
 	const hasComments = comments.length > 0;
+	const commentPlan = planCommentParts(comments);
 	try {
 		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;
@@ -215,9 +216,8 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		}
 		const sourceCommentsFile = zip.file("word/comments.xml");
 		if (hasComments || sourceCommentsFile) {
-			ensureThreadedCommentParaIds(comments);
 			const sourceBindings = sourceCommentsFile ? readRootNamespaceBindings(await sourceCommentsFile.async("text")) : void 0;
-			updates.set("word/comments.xml", serializeComments(comments, sourceBindings));
+			updates.set("word/comments.xml", serializeComments(commentPlan, sourceBindings));
 		}
 		if (hasComments) {
 			const ctFile = zip.file("[Content_Types].xml");
@@ -235,7 +235,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				}
 			}
 		}
-		if (!await patchCommentsExtended(zip, comments, updates)) return null;
+		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
 		await patchNumberingPart(zip, doc, updates);
 		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);

package/dist/docx/selectiveXmlPatch.d.ts

@@ -109,6 +109,24 @@ declare function buildPatchedDocumentXml(originalXml: string, serializedXml: str
  * the caller can fall back to preserving the original part verbatim.
  */
 declare function buildPatchedNoteXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+/** One region of a part replaced by re-serialized XML. */
+type XmlSplice = {
+  start: number;
+  end: number;
+  newXml: string;
+};
+/**
+ * Apply `splices` to `xml`, end-to-start so earlier offsets stay valid.
+ *
+ * Every selective patch is a splice, and every splice goes through here, so
+ * the refusal below is a property of the operation rather than a check each
+ * site has to remember. A patch rewrites the regions an edit touched and keeps
+ * the rest of the part byte-for-byte, so it can write half a comment range:
+ * invalid OOXML that anchors the comment to nothing. Answers null when it
+ * would, leaving the caller to rewrite a wider region — ultimately the whole
+ * part from the model, which is balanced with itself.
+ */
+declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
 type NoteElementName = "footnote" | "endnote";
 declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
 type BuildPatchedNotePartXmlOptions = {
@@ -119,6 +137,25 @@ type BuildPatchedNotePartXmlOptions = {
   elementName: NoteElementName;
   changedParaIds?: ReadonlySet<string>;
 };
+/** Why a note part could not be patched; see {@link NotePartPatch}. */
+type NotePartPatchRefusal =
+/** A note element, or a changed paragraph, was missing or ambiguous. */
+"unroutable-paragraph" |
+/** Even rewriting whole notes would leave a comment range with one half. */
+"comment-range-balance";
+/**
+ * What patching a note part produced. `refused` is not a failure to serialize:
+ * the caller writes the part from the model instead, the note-part reading of
+ * the fall back to a full repack the document story takes when its own splice
+ * is refused.
+ */
+type NotePartPatch = {
+  type: "patched";
+  xml: string;
+} | {
+  type: "refused";
+  reason: NotePartPatchRefusal;
+};
 /**
  * Patch an existing note part from its model serialization.
  *
@@ -130,8 +167,15 @@ type BuildPatchedNotePartXmlOptions = {
  * notes, and unaffected equal-shape paragraphs remain byte-exact.
  * `replacementXml` also supplies synthesized automatic note-reference marks,
  * which the parsed model intentionally omits.
+ *
+ * A comment can be anchored on a note's own text, so its range spans that
+ * note's paragraphs and an edit inside the span moves a range half from one
+ * paragraph to another. Replacing only the dirty paragraph then drops the half
+ * it held and leaves the other standing, so {@link spliceXml} refuses the
+ * result and the changed notes are rewritten whole instead — model content on
+ * both sides of the range, with every other note still byte-exact.
  */
-declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): string | null;
+declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): NotePartPatch;
 type ChangedNumberingDefs = {
   abstractNums: Set<string>;
   nums: Set<string>;
@@ -178,4 +222,4 @@ declare const patchNumberingDefinitions: ({ originalXml, baselineXml, currentXml
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, validatePatchSafety };
+export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, spliceXml, validatePatchSafety };