@stll/folio-core 0.43.0 → 0.45.0

package/dist/docx/serializer/paragraphSerializer.js

@@ -5,12 +5,14 @@ import { DATE_UTC_ATTRIBUTE } from "../trackedChangeInfo.js";
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { captureVerbatimXml, sanitizeCapturedXmlElement } from "../verbatimCapture.js";
 import { NAMESPACES, OOXML_NAMESPACE_SCOPE, cloneElement, getChildElements, getLocalName, parseXml } from "../xmlParser.js";
+import { bookmarkRangeAttributes, markupRangeAttributes, moveBookmarkAttributes } from "./markupRangeAttributes.js";
 import { serializeRun } from "./runSerializer.js";
 import { serializeSectionProperties } from "./sectionPropertiesSerializer.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
 import { serializeTrackedChangeAttributes, trackedChangeAttributeRecord } from "./trackedChangeAttributes.js";
-import { escapeXml, isSingleWellFormedElement } from "./xmlUtils.js";
+import { isSingleWellFormedElement } from "./xmlUtils.js";
 import { panic } from "better-result";
+import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
 import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 //#region src/docx/serializer/paragraphSerializer.ts
 /**
@@ -21,13 +23,20 @@ function serializeParagraphMarkChange(mark) {
 	return `<w:${mark.kind} ${attrs}/>`;
 }
 const RESERVED_PARAGRAPH_PROPERTY_CHILDREN = /* @__PURE__ */ new Set(["pPrChange", "sectPr"]);
+/**
+* Revision records a captured `w:pPr` may not carry into a replay.
+*
+* `w:numberingChange` is not among them: the model holds it
+* (`ParagraphFormatting.numberingChangeXml`) and the serializer writes it
+* back, so both paths keep it. Refusing the capture used to force a rebuild
+* that could not write it, which turned a replay gate into a lost revision.
+*/
 const RESERVED_PARAGRAPH_CAPTURE_CHILDREN = /* @__PURE__ */ new Set([
 	...RESERVED_PARAGRAPH_PROPERTY_CHILDREN,
 	...PARAGRAPH_MARK_CHANGE_KINDS,
 	"cellDel",
 	"cellIns",
 	"cellMerge",
-	"numberingChange",
 	"rPrChange",
 	"tblGridChange",
 	"tblPrChange",
@@ -119,7 +128,11 @@ const PARAGRAPH_MARK_BASE_CHILDREN = /* @__PURE__ */ new Set([
 	"oMath"
 ]);
 const PARAGRAPH_NESTED_PROPERTY_CHILDREN = /* @__PURE__ */ new Map([
-	["numPr", /* @__PURE__ */ new Set(["ilvl", "numId"])],
+	["numPr", /* @__PURE__ */ new Set([
+		"ilvl",
+		"numId",
+		"numberingChange"
+	])],
 	["pBdr", /* @__PURE__ */ new Set([
 		"top",
 		"left",
@@ -319,13 +332,13 @@ function serializeParagraphPropertyChange(change) {
 /** The attribute list of a `w:hyperlink`, without its children. */
 function hyperlinkAttributes(hyperlink) {
 	const attrs = [];
-	if (hyperlink.rId) attrs.push(`r:id="${escapeXml(hyperlink.rId)}"`);
-	if (hyperlink.anchor) attrs.push(`w:anchor="${escapeXml(hyperlink.anchor)}"`);
-	if (hyperlink.tooltip) attrs.push(`w:tooltip="${escapeXml(hyperlink.tooltip)}"`);
-	if (hyperlink.target) attrs.push(`w:tgtFrame="${escapeXml(hyperlink.target)}"`);
+	if (hyperlink.rId) attrs.push(`r:id="${escapeXmlAttribute(hyperlink.rId)}"`);
+	if (hyperlink.anchor) attrs.push(`w:anchor="${escapeXmlAttribute(hyperlink.anchor)}"`);
+	if (hyperlink.tooltip) attrs.push(`w:tooltip="${escapeXmlAttribute(hyperlink.tooltip)}"`);
+	if (hyperlink.target) attrs.push(`w:tgtFrame="${escapeXmlAttribute(hyperlink.target)}"`);
 	if (hyperlink.history === true) attrs.push("w:history=\"1\"");
 	else if (hyperlink.history === false) attrs.push("w:history=\"0\"");
-	if (hyperlink.docLocation) attrs.push(`w:docLocation="${escapeXml(hyperlink.docLocation)}"`);
+	if (hyperlink.docLocation) attrs.push(`w:docLocation="${escapeXmlAttribute(hyperlink.docLocation)}"`);
 	return attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
 }
 /** One `w:hyperlink` child, with the caller deciding how a run is written. */
@@ -344,20 +357,17 @@ function serializeHyperlink(hyperlink) {
 * Serialize bookmark start (w:bookmarkStart)
 */
 function serializeBookmarkStart(bookmark) {
-	const attrs = [`w:id="${bookmark.id}"`, `w:name="${escapeXml(bookmark.name)}"`];
-	if (bookmark.colFirst !== void 0) attrs.push(`w:colFirst="${bookmark.colFirst}"`);
-	if (bookmark.colLast !== void 0) attrs.push(`w:colLast="${bookmark.colLast}"`);
-	return `<w:bookmarkStart ${attrs.join(" ")}/>`;
+	return `<w:bookmarkStart ${bookmarkRangeAttributes(bookmark).join(" ")}/>`;
 }
 /**
 * Serialize bookmark end (w:bookmarkEnd)
 */
 function serializeBookmarkEnd(bookmark) {
-	return `<w:bookmarkEnd w:id="${bookmark.id}"/>`;
+	return `<w:bookmarkEnd ${markupRangeAttributes(bookmark).join(" ")}/>`;
 }
 /** Serialize a simple field without changing its authored OOXML field form. */
 function serializeSimpleField(field) {
-	const attrs = [`w:instr="${escapeXml(field.instruction)}"`];
+	const attrs = [`w:instr="${escapeXmlAttribute(field.instruction)}"`];
 	if (field.fldLock) attrs.push("w:fldLock=\"true\"");
 	if (field.dirty) attrs.push("w:dirty=\"true\"");
 	const contentXml = field.content.map((item) => item.type === "run" ? serializeRun(item) : serializeHyperlink(item)).join("");
@@ -379,7 +389,7 @@ function serializeComplexField(field) {
 	if (field.fieldCode.length > 0) parts.push(...field.fieldCode.map((run) => serializeRun(run)));
 	else if (field.instruction.length > 0) {
 		const spaceAttr = field.instruction.startsWith(" ") || field.instruction.endsWith(" ") || field.instruction.includes("  ") ? " xml:space=\"preserve\"" : "";
-		parts.push(`<w:r>${rPrXml}<w:instrText${spaceAttr}>${escapeXml(field.instruction)}</w:instrText></w:r>`);
+		parts.push(`<w:r>${rPrXml}<w:instrText${spaceAttr}>${escapeXmlText(field.instruction)}</w:instrText></w:r>`);
 	}
 	parts.push(`<w:r>${rPrXml}<w:fldChar w:fldCharType="separate"/></w:r>`);
 	parts.push(...field.fieldResult.map((run) => serializeRun(run)));
@@ -397,29 +407,29 @@ function serializeComplexField(field) {
 function synthesizeInlineSdtPr(props) {
 	const prParts = [];
 	if (typeof props.id === "number") prParts.push(`<w:id w:val="${props.id}"/>`);
-	if (props.alias) prParts.push(`<w:alias w:val="${escapeXml(props.alias)}"/>`);
-	if (props.tag) prParts.push(`<w:tag w:val="${escapeXml(props.tag)}"/>`);
+	if (props.alias) prParts.push(`<w:alias w:val="${escapeXmlAttribute(props.alias)}"/>`);
+	if (props.tag) prParts.push(`<w:tag w:val="${escapeXmlAttribute(props.tag)}"/>`);
 	if (props.lock && props.lock !== "unlocked") prParts.push(`<w:lock w:val="${props.lock}"/>`);
-	if (props.placeholder) prParts.push(`<w:placeholder><w:docPart w:val="${escapeXml(props.placeholder)}"/></w:placeholder>`);
+	if (props.placeholder) prParts.push(`<w:placeholder><w:docPart w:val="${escapeXmlAttribute(props.placeholder)}"/></w:placeholder>`);
 	if (props.showingPlaceholder) prParts.push("<w:showingPlcHdr/>");
 	switch (props.sdtType) {
 		case "plainText":
 			prParts.push("<w:text/>");
 			break;
 		case "date": {
-			const fullDateAttr = props.dateValueISO ? ` w:fullDate="${escapeXml(props.dateValueISO)}"` : "";
-			const formatChild = props.dateFormat ? `<w:dateFormat w:val="${escapeXml(props.dateFormat)}"/>` : "";
+			const fullDateAttr = props.dateValueISO ? ` w:fullDate="${escapeXmlAttribute(props.dateValueISO)}"` : "";
+			const formatChild = props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttribute(props.dateFormat)}"/>` : "";
 			if (fullDateAttr || formatChild) prParts.push(`<w:date${fullDateAttr}>${formatChild}</w:date>`);
 			else prParts.push("<w:date/>");
 			break;
 		}
 		case "dropdown": {
-			const items = (props.listItems ?? []).map((i) => `<w:listItem w:displayText="${escapeXml(i.displayText)}" w:value="${escapeXml(i.value)}"/>`).join("");
+			const items = (props.listItems ?? []).map((i) => `<w:listItem w:displayText="${escapeXmlAttribute(i.displayText)}" w:value="${escapeXmlAttribute(i.value)}"/>`).join("");
 			prParts.push(`<w:dropDownList>${items}</w:dropDownList>`);
 			break;
 		}
 		case "comboBox": {
-			const items = (props.listItems ?? []).map((i) => `<w:listItem w:displayText="${escapeXml(i.displayText)}" w:value="${escapeXml(i.value)}"/>`).join("");
+			const items = (props.listItems ?? []).map((i) => `<w:listItem w:displayText="${escapeXmlAttribute(i.displayText)}" w:value="${escapeXmlAttribute(i.value)}"/>`).join("");
 			prParts.push(`<w:comboBox>${items}</w:comboBox>`);
 			break;
 		}
@@ -471,7 +481,7 @@ function serializeInlineSdt(sdt) {
 	})}${props.rawEndPropertiesXml && isSingleWellFormedElement(props.rawEndPropertiesXml, "sdtEndPr") ? props.rawEndPropertiesXml : ""}<w:sdtContent>${contentXml}</w:sdtContent></w:sdt>`;
 }
 function serializeMoveRangeStart(tag, marker) {
-	return `<w:${tag} ${[`w:id="${marker.id}"`, `w:name="${escapeXml(marker.name)}"`].join(" ")}/>`;
+	return `<w:${tag} ${moveBookmarkAttributes(marker).join(" ")}/>`;
 }
 /**
 * Serialize a tracked change wrapper (ins/del/moveFrom/moveTo)
@@ -560,17 +570,24 @@ function serializeParagraphContent(content, explicitCommentReferenceIds) {
 		case "simpleField": return serializeSimpleField(content);
 		case "complexField": return serializeComplexField(content);
 		case "inlineSdt": return serializeInlineSdt(content);
-		case "commentRangeStart": return `<w:commentRangeStart w:id="${content.id}"/>`;
-		case "commentRangeEnd": return explicitCommentReferenceIds.has(content.id) ? `<w:commentRangeEnd w:id="${content.id}"/>` : `<w:commentRangeEnd w:id="${content.id}"/>${serializeCommentReferenceRun(content.id)}`;
+		case "commentRangeStart": return `<w:commentRangeStart ${markupRangeAttributes(content).join(" ")}/>`;
+		case "commentRangeEnd": {
+			const end = `<w:commentRangeEnd ${markupRangeAttributes(content).join(" ")}/>`;
+			return explicitCommentReferenceIds.has(content.id) ? end : `${end}${serializeCommentReferenceRun(content.id)}`;
+		}
 		case "commentReference": return serializeCommentReferenceRun(content.id);
 		case "insertion": return serializeTrackedChange("ins", content);
 		case "deletion": return serializeTrackedChange("del", content);
 		case "moveFrom": return serializeTrackedChange("moveFrom", content);
 		case "moveTo": return serializeTrackedChange("moveTo", content);
 		case "moveFromRangeStart": return serializeMoveRangeStart("moveFromRangeStart", content);
-		case "moveFromRangeEnd": return `<w:moveFromRangeEnd w:id="${content.id}"/>`;
+		case "moveFromRangeEnd": return `<w:moveFromRangeEnd ${markupRangeAttributes(content).join(" ")}/>`;
 		case "moveToRangeStart": return serializeMoveRangeStart("moveToRangeStart", content);
-		case "moveToRangeEnd": return `<w:moveToRangeEnd w:id="${content.id}"/>`;
+		case "moveToRangeEnd": return `<w:moveToRangeEnd ${markupRangeAttributes(content).join(" ")}/>`;
+		case "bidiWrapper": {
+			const tag = content.control === "override" ? "bdo" : "dir";
+			return `<w:${tag}${content.direction === void 0 ? "" : ` w:val="${escapeXmlAttribute(content.direction)}"`}>${content.content.map((child) => serializeParagraphContent(child, explicitCommentReferenceIds)).join("")}</w:${tag}>`;
+		}
 		case "mathEquation": return content.ommlXml || "";
 		default: return "";
 	}
@@ -584,8 +601,8 @@ function serializeParagraphContent(content, explicitCommentReferenceIds) {
 function serializeParagraph(paragraph) {
 	const parts = [];
 	const attrs = [];
-	if (paragraph.paraId) attrs.push(`w14:paraId="${escapeXml(paragraph.paraId)}"`);
-	if (paragraph.textId) attrs.push(`w14:textId="${escapeXml(paragraph.textId)}"`);
+	if (paragraph.paraId) attrs.push(`w14:paraId="${escapeXmlAttribute(paragraph.paraId)}"`);
+	if (paragraph.textId) attrs.push(`w14:textId="${escapeXmlAttribute(paragraph.textId)}"`);
 	if (paragraph.reviewCarrier) attrs.push(`folio:reviewCarrier="${paragraph.reviewCarrier}"`);
 	const attrsStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
 	parts.push(serializeParagraphFormattingWithOptions(paragraph.formatting, {
@@ -657,28 +674,6 @@ function hasParagraphFormatting(paragraph) {
 	return paragraph.formatting !== void 0 && Object.keys(paragraph.formatting).length > 0;
 }
 /**
-* Get plain text from a paragraph (for comparison/debugging)
-*/
-function getParagraphPlainText(paragraph) {
-	const texts = [];
-	for (const content of paragraph.content) if (content.type === "run") {
-		for (const item of content.content) if (item.type === "text") texts.push(item.text);
-		else if (item.type === "tab") texts.push("	");
-		else if (item.type === "break") texts.push("\n");
-	} else if (content.type === "hyperlink") {
-		for (const child of content.children) if (child.type === "run") {
-			for (const item of child.content) if (item.type === "text") texts.push(item.text);
-		}
-	} else if (content.type === "simpleField" || content.type === "inlineSdt" || content.type === "insertion" || content.type === "deletion" || content.type === "moveFrom" || content.type === "moveTo") {
-		for (const item of content.content) if (item.type === "run") {
-			for (const subItem of item.content) if (subItem.type === "text") texts.push(subItem.text);
-		}
-	} else if (content.type === "complexField") {
-		for (const run of content.fieldResult) for (const item of run.content) if (item.type === "text") texts.push(item.text);
-	}
-	return texts.join("");
-}
-/**
 * Create an empty paragraph
 */
 function createEmptyParagraph(formatting) {
@@ -718,4 +713,4 @@ function getListLevel(paragraph) {
 	return paragraph.formatting?.numPr?.ilvl ?? -1;
 }
 //#endregion
-export { createEmptyParagraph, createTextParagraph, getListLevel, getParagraphPlainText, hasParagraphContent, hasParagraphFormatting, isListParagraph, serializeParagraph, serializeParagraphFormatting, serializeParagraphs };
+export { createEmptyParagraph, createTextParagraph, getListLevel, hasParagraphContent, hasParagraphFormatting, isListParagraph, serializeParagraph, serializeParagraphFormatting, serializeParagraphs };

package/dist/docx/serializer/partNamespaces.js

@@ -1,6 +1,6 @@
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
-import { escapeXml } from "./xmlUtils.js";
 import { TaggedError } from "better-result";
+import { escapeXmlAttribute } from "@stll/docx-core";
 import { OOXML_NS } from "@stll/docx-utils";
 //#region src/docx/serializer/partNamespaces.ts
 /**
@@ -319,7 +319,7 @@ const serializePartElement = ({ partPath, rootName, rootAttributes, baselinePref
 		...[...NAMESPACE_TABLE.keys()].filter((prefix) => extra.has(prefix)),
 		...[...extra].filter((prefix) => !NAMESPACE_TABLE.has(prefix)).sort()
 	];
-	const attributes = orderedPrefixes.map((prefix) => `xmlns:${prefix}="${escapeXml(bindings.get(prefix))}"`);
+	const attributes = orderedPrefixes.map((prefix) => `xmlns:${prefix}="${escapeXmlAttribute(bindings.get(prefix))}"`);
 	const ignorable = orderedPrefixes.filter((prefix) => NAMESPACE_TABLE.get(prefix)?.ignorable === true);
 	if (ignorable.length > 0) attributes.push(`mc:Ignorable="${ignorable.join(" ")}"`);
 	return `${openingTag} ${attributes.join(" ")}>${body}</${rootName}>`;

package/dist/docx/serializer/runSerializer.js

@@ -1,14 +1,16 @@
 import { isValidHexColor } from "../../utils/colorResolver.js";
 import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
 import { serializeGraphicFrameLocks } from "../graphicFrameLocks.js";
+import { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE } from "../imageParser.js";
 import { canReplayEditableImageRawXml } from "../imageRawXml.js";
-import { requiresXmlSpacePreserve } from "../textWhitespace.js";
+import { serializeNonVisualDrawingNames } from "../nonVisualDrawingProps.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializeTable } from "./tableSerializer.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
 import { getSingularRunPropertyChange, serializeTrackedChangeAttributes } from "./trackedChangeAttributes.js";
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
 import { panic } from "better-result";
+import { escapeXmlAttribute, escapeXmlText, requiresXmlSpacePreserve } from "@stll/docx-core";
 //#region src/docx/serializer/runSerializer.ts
 /**
 * Run Serializer - Serialize runs to OOXML XML
@@ -59,7 +61,7 @@ function serializeRunProperties(formatting, propertyChanges) {
 * Serialize text content (w:t)
 */
 function serializeTextContent(content) {
-	return `<w:t${content.preserveSpace || requiresXmlSpacePreserve(content.text) ? " xml:space=\"preserve\"" : ""}>${escapeXml(content.text)}</w:t>`;
+	return `<w:t${requiresXmlSpacePreserve(content.text) ? " xml:space=\"preserve\"" : ""}>${escapeXmlText(content.text)}</w:t>`;
 }
 /**
 * Serialize tab content (w:tab)
@@ -67,9 +69,9 @@ function serializeTextContent(content) {
 function serializeTabContent(content) {
 	if (!content.positional) return "<w:tab/>";
 	return `<w:ptab${[
-		content.positional.relativeTo ? ` w:relativeTo="${escapeXml(content.positional.relativeTo)}"` : "",
-		content.positional.alignment ? ` w:alignment="${escapeXml(content.positional.alignment)}"` : "",
-		content.positional.leader ? ` w:leader="${escapeXml(content.positional.leader)}"` : ""
+		content.positional.relativeTo ? ` w:relativeTo="${escapeXmlAttribute(content.positional.relativeTo)}"` : "",
+		content.positional.alignment ? ` w:alignment="${escapeXmlAttribute(content.positional.alignment)}"` : "",
+		content.positional.leader ? ` w:leader="${escapeXmlAttribute(content.positional.leader)}"` : ""
 	].join("")}/>`;
 }
 /**
@@ -88,7 +90,7 @@ function serializeBreakContent(content) {
 * Serialize symbol content (w:sym)
 */
 function serializeSymbolContent(content) {
-	return `<w:sym w:font="${escapeXml(content.font)}" w:char="${escapeXml(content.char)}"/>`;
+	return `<w:sym${content.font === "" ? "" : ` w:font="${escapeXmlAttribute(content.font)}"`}${content.char === "" ? "" : ` w:char="${escapeXmlAttribute(content.char)}"`}/>`;
 }
 /**
 * Serialize footnote/endnote reference
@@ -110,7 +112,7 @@ function serializeFieldChar(content) {
 * Serialize field instruction text (w:instrText)
 */
 function serializeInstrText(content) {
-	return `<w:instrText${content.text.startsWith(" ") || content.text.endsWith(" ") || content.text.includes("  ") ? " xml:space=\"preserve\"" : ""}>${escapeXml(content.text)}</w:instrText>`;
+	return `<w:instrText${content.text.startsWith(" ") || content.text.endsWith(" ") || content.text.includes("  ") ? " xml:space=\"preserve\"" : ""}>${escapeXmlText(content.text)}</w:instrText>`;
 }
 /**
 * Serialize soft hyphen (w:softHyphen)
@@ -127,11 +129,11 @@ function serializeNoBreakHyphen(_content) {
 /** Serialize a color value to DrawingML a:srgbClr or a:schemeClr */
 function serializeDrawingColor(color) {
 	if (!color) return "";
-	if (color.rgb && isValidHexColor(color.rgb)) return `<a:srgbClr val="${escapeXml(color.rgb.replace("#", ""))}"/>`;
+	if (color.rgb && isValidHexColor(color.rgb)) return `<a:srgbClr val="${escapeXmlAttribute(color.rgb.replace("#", ""))}"/>`;
 	if (color.themeColor) {
 		let clr = `<a:schemeClr val="${THEME_COLOR_TO_DRAWING_SCHEME[color.themeColor]}"`;
-		if (color.themeTint) clr += `><a:tint val="${escapeXml(color.themeTint)}"/></a:schemeClr>`;
-		else if (color.themeShade) clr += `><a:shade val="${escapeXml(color.themeShade)}"/></a:schemeClr>`;
+		if (color.themeTint) clr += `><a:tint val="${escapeXmlAttribute(color.themeTint)}"/></a:schemeClr>`;
+		else if (color.themeShade) clr += `><a:shade val="${escapeXmlAttribute(color.themeShade)}"/></a:schemeClr>`;
 		else clr += `/>`;
 		return clr;
 	}
@@ -206,11 +208,17 @@ function serializeWrap(wrap) {
 		case "inline": return "<wp:wrapNone/>";
 	}
 }
-/** Build the common a:graphic > pic:pic element for images */
-function serializePicGraphic(image, sharedId) {
+/**
+* Build the common a:graphic > pic:pic element for images.
+*
+* Takes the relationship id as a separate argument so the caller has to have
+* one. There is no default: a picture written against an invented id binds to
+* whichever relationship the part happens to hold under that name.
+*/
+function serializePicGraphic(image, imageRId, sharedId) {
 	const cx = image.size.width;
 	const cy = image.size.height;
-	const rId = escapeXml(image.rId || "rId1");
+	const rId = escapeXmlAttribute(imageRId);
 	const id = sharedId;
 	const name = image.filename || `image${id}`;
 	let xfrmAttrs = "";
@@ -230,7 +238,7 @@ function serializePicGraphic(image, sharedId) {
 		"<a:graphicData uri=\"http://schemas.openxmlformats.org/drawingml/2006/picture\">",
 		"<pic:pic xmlns:pic=\"http://schemas.openxmlformats.org/drawingml/2006/picture\">",
 		"<pic:nvPicPr>",
-		`<pic:cNvPr id="${id}" name="${escapeXml(name)}"${image.alt ? ` descr="${escapeXml(image.alt)}"` : ""}/>`,
+		`<pic:cNvPr id="${id}" name="${escapeXmlAttribute(name)}"${image.alt ? ` descr="${escapeXmlAttribute(image.alt)}"` : ""}/>`,
 		"<pic:cNvPicPr/>",
 		"</pic:nvPicPr>",
 		"<pic:blipFill>",
@@ -264,6 +272,19 @@ function serializeWrapDistanceAttrs(wrap) {
 	return attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
 }
 /**
+* Serialize the `wp:docPr` extension list.
+*
+* The decorative flag is the one extension folio models; every other `a:ext`
+* the source carried is replayed as it was captured, in its original order,
+* because an extension dropped on save is a fact the document had and lost.
+* The decorative extension goes first: it is the one folio may have added.
+*/
+function serializeDocPrExtensions(image) {
+	const preserved = image.docPrExtensions ?? [];
+	const entries = `${image.decorative === void 0 ? "" : `<a:ext uri="${DECORATIVE_EXTENSION_URI}"><adec:decorative xmlns:adec="${DECORATIVE_NAMESPACE}" val="${image.decorative ? "1" : "0"}"/></a:ext>`}${preserved.join("")}`;
+	return entries ? `<a:extLst>${entries}</a:extLst>` : "";
+}
+/**
 * Serialize drawing/image content (w:drawing) to full DrawingML XML
 */
 function serializeDrawingContent(content) {
@@ -278,22 +299,23 @@ function serializeDrawingContent(content) {
 	const effB = image.padding?.bottom ?? 0;
 	const effectExtentEl = `<wp:effectExtent l="${intAttr(effL)}" t="${intAttr(effT)}" r="${intAttr(effR)}" b="${intAttr(effB)}"/>`;
 	const docPrId = getUniqueId(image.id);
-	const docPrName = image.docPrName ?? image.filename ?? `Picture ${docPrId}`;
-	const docPrDescription = image.alt !== void 0 ? ` descr="${escapeXml(image.alt)}"` : "";
-	const docPrTitle = image.title !== void 0 ? ` title="${escapeXml(image.title)}"` : "";
-	const hlinkClick = image.hlinkRId ? `<a:hlinkClick r:id="${escapeXml(image.hlinkRId)}"/>` : "";
-	const inlineDocPrAttrs = `id="${docPrId}" name="${escapeXml(docPrName)}"${docPrDescription}${docPrTitle}${image.decorative ? " hidden=\"1\"" : ""}`;
-	const inlineDocPr = hlinkClick ? `<wp:docPr ${inlineDocPrAttrs}>${hlinkClick}</wp:docPr>` : `<wp:docPr ${inlineDocPrAttrs}/>`;
-	const anchorDocPrAttrs = `id="${docPrId}" name="${escapeXml(docPrName)}"${docPrDescription}${docPrTitle}`;
-	const anchorDocPr = hlinkClick ? `<wp:docPr ${anchorDocPrAttrs}>${hlinkClick}</wp:docPr>` : `<wp:docPr ${anchorDocPrAttrs}/>`;
+	const docPrNames = serializeNonVisualDrawingNames({
+		...image.docPrName !== void 0 ? { name: image.docPrName } : {},
+		...image.alt !== void 0 ? { alt: image.alt } : {},
+		...image.title !== void 0 ? { title: image.title } : {}
+	});
+	const hlinkClick = image.hlinkRId ? `<a:hlinkClick r:id="${escapeXmlAttribute(image.hlinkRId)}"/>` : "";
+	const docPrAttrs = `id="${docPrId}"${docPrNames}${image.hidden === void 0 ? "" : ` hidden="${image.hidden ? "1" : "0"}"`}`;
+	const docPrChildren = `${hlinkClick}${serializeDocPrExtensions(image)}`;
+	const docPr = docPrChildren ? `<wp:docPr ${docPrAttrs}>${docPrChildren}</wp:docPr>` : `<wp:docPr ${docPrAttrs}/>`;
 	const graphicFramePr = serializeGraphicFrameLocks(image.frameLocks);
-	const graphic = serializePicGraphic(image, docPrId);
+	const graphic = image.rId === void 0 ? "" : serializePicGraphic(image, image.rId, docPrId);
 	if (!isFloating) return [
 		"<w:drawing>",
 		`<wp:inline${wrapDistanceAttrs}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
-		inlineDocPr,
+		docPr,
 		graphicFramePr,
 		graphic,
 		"</wp:inline>",
@@ -310,7 +332,7 @@ function serializeDrawingContent(content) {
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
 		wrap,
-		anchorDocPr,
+		docPr,
 		graphicFramePr,
 		graphic,
 		"</wp:anchor>",
@@ -333,7 +355,7 @@ const serializeTextBodyAnchor = (anchor) => {
 };
 function serializeGeometryAdjustments(shape) {
 	if (!shape.geometryAdjustments || shape.geometryAdjustments.length === 0) return "<a:avLst/>";
-	return `<a:avLst>${shape.geometryAdjustments.map(({ name, formula }) => `<a:gd name="${escapeXml(name)}" fmla="${escapeXml(formula)}"/>`).join("")}</a:avLst>`;
+	return `<a:avLst>${shape.geometryAdjustments.map(({ name, formula }) => `<a:gd name="${escapeXmlAttribute(name)}" fmla="${escapeXmlAttribute(formula)}"/>`).join("")}</a:avLst>`;
 }
 /**
 * Serialize shape content to full DrawingML XML (wps:wsp inside w:drawing)
@@ -346,7 +368,11 @@ function serializeShapeContent(content) {
 	const isFloating = shape.wrap && shape.wrap.type !== "inline";
 	const wrapDistances = serializeWrapDistanceAttrs(shape.wrap);
 	const docPrId = getUniqueId(shape.id);
-	const docPrName = shape.name ?? (isTextBox ? `TextBox ${docPrId}` : `Shape ${docPrId}`);
+	const docPrNames = serializeNonVisualDrawingNames({
+		...shape.name !== void 0 ? { name: shape.name } : {},
+		...shape.alt !== void 0 ? { alt: shape.alt } : {},
+		...shape.title !== void 0 ? { title: shape.title } : {}
+	});
 	let xfrmAttrs = "";
 	if (shape.transform?.rotation) xfrmAttrs += ` rot="${Math.round(shape.transform.rotation * 6e4)}"`;
 	if (shape.transform?.flipH) xfrmAttrs += " flipH=\"1\"";
@@ -380,7 +406,7 @@ function serializeShapeContent(content) {
 		if (tb.autoFit === "shape") autoFitXml = "<a:spAutoFit/>";
 		else if (tb.autoFit === "normal") autoFitXml = "<a:normAutofit/>";
 		else if (tb.autoFit === "none") autoFitXml = "<a:noAutofit/>";
-		const bodyPrChildren = `${tb.wordArt?.preset ? `<a:prstTxWarp prst="${escapeXml(tb.wordArt.preset)}">${tb.wordArt.adjustments && tb.wordArt.adjustments.length > 0 ? `<a:avLst>${tb.wordArt.adjustments.map(({ name, formula }) => `<a:gd name="${escapeXml(name)}" fmla="${escapeXml(formula)}"/>`).join("")}</a:avLst>` : "<a:avLst/>"}</a:prstTxWarp>` : ""}${autoFitXml}`;
+		const bodyPrChildren = `${tb.wordArt?.preset ? `<a:prstTxWarp prst="${escapeXmlAttribute(tb.wordArt.preset)}">${tb.wordArt.adjustments && tb.wordArt.adjustments.length > 0 ? `<a:avLst>${tb.wordArt.adjustments.map(({ name, formula }) => `<a:gd name="${escapeXmlAttribute(name)}" fmla="${escapeXmlAttribute(formula)}"/>`).join("")}</a:avLst>` : "<a:avLst/>"}</a:prstTxWarp>` : ""}${autoFitXml}`;
 		const bodyPrXml = bodyPrChildren ? `<wps:bodyPr ${bpAttrs.join(" ")}>${bodyPrChildren}</wps:bodyPr>` : `<wps:bodyPr ${bpAttrs.join(" ")}/>`;
 		if (isTextBox) textBody = [
 			"<wps:txbx><w:txbxContent>",
@@ -408,7 +434,7 @@ function serializeShapeContent(content) {
 		`<wp:inline${wrapDistances}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
-		`<wp:docPr id="${docPrId}" name="${escapeXml(docPrName)}"/>`,
+		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
 		graphic,
 		"</wp:inline>",
@@ -426,7 +452,7 @@ function serializeShapeContent(content) {
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
 		wrap,
-		`<wp:docPr id="${docPrId}" name="${escapeXml(docPrName)}"/>`,
+		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
 		graphic,
 		"</wp:anchor>",

package/dist/docx/serializer/sectionPropertiesSerializer.js

@@ -2,10 +2,11 @@ import { getUnserializedSectionPropertyChildNames } from "../sectionParser.js";
 import { serializeSectionReferenceHistory } from "../sectionReferenceHistory.js";
 import { serializeBorder } from "./borderSerializer.js";
 import { serializeTrackedChangeAttributes } from "./trackedChangeAttributes.js";
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/sectionPropertiesSerializer.ts
-const serializeHeaderReference = (ref) => `<w:headerReference w:type="${ref.type}" r:id="${escapeXml(ref.rId)}"/>`;
-const serializeFooterReference = (ref) => `<w:footerReference w:type="${ref.type}" r:id="${escapeXml(ref.rId)}"/>`;
+const serializeHeaderReference = (ref) => `<w:headerReference w:type="${ref.type}" r:id="${escapeXmlAttribute(ref.rId)}"/>`;
+const serializeFooterReference = (ref) => `<w:footerReference w:type="${ref.type}" r:id="${escapeXmlAttribute(ref.rId)}"/>`;
 function serializeFootnoteProperties(props) {
 	if (!props) return "";
 	const parts = [];
@@ -84,7 +85,7 @@ function serializePageNumbering(props) {
 	if (pageNumbering.format) attrs.push(`w:fmt="${pageNumbering.format}"`);
 	if (pageNumbering.start !== void 0) attrs.push(`w:start="${intAttr(pageNumbering.start)}"`);
 	if (pageNumbering.chapterStyle !== void 0) attrs.push(`w:chapStyle="${intAttr(pageNumbering.chapterStyle)}"`);
-	if (pageNumbering.chapterSeparator) attrs.push(`w:chapSep="${escapeXml(pageNumbering.chapterSeparator)}"`);
+	if (pageNumbering.chapterSeparator) attrs.push(`w:chapSep="${escapeXmlAttribute(pageNumbering.chapterSeparator)}"`);
 	return attrs.length > 0 ? `<w:pgNumType ${attrs.join(" ")}/>` : "";
 }
 function serializePageBorders(props) {
@@ -114,10 +115,10 @@ function serializeBackground(props) {
 	const attrs = [];
 	const { background } = props;
 	if (background.color?.auto) attrs.push("w:color=\"auto\"");
-	else if (background.color?.rgb) attrs.push(`w:color="${escapeXml(background.color.rgb)}"`);
-	if (background.themeColor ?? background.color?.themeColor) attrs.push(`w:themeColor="${escapeXml(background.themeColor ?? background.color?.themeColor ?? "")}"`);
-	if (background.themeTint ?? background.color?.themeTint) attrs.push(`w:themeTint="${escapeXml(background.themeTint ?? background.color?.themeTint ?? "")}"`);
-	if (background.themeShade ?? background.color?.themeShade) attrs.push(`w:themeShade="${escapeXml(background.themeShade ?? background.color?.themeShade ?? "")}"`);
+	else if (background.color?.rgb) attrs.push(`w:color="${escapeXmlAttribute(background.color.rgb)}"`);
+	if (background.themeColor ?? background.color?.themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(background.themeColor ?? background.color?.themeColor ?? "")}"`);
+	if (background.themeTint ?? background.color?.themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(background.themeTint ?? background.color?.themeTint ?? "")}"`);
+	if (background.themeShade ?? background.color?.themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(background.themeShade ?? background.color?.themeShade ?? "")}"`);
 	return attrs.length > 0 ? `<w:background ${attrs.join(" ")}/>` : "";
 }
 function serializeDocGrid(props) {
@@ -127,7 +128,7 @@ function serializeDocGrid(props) {
 	if (dg.type) attrs.push(`w:type="${dg.type}"`);
 	if (dg.linePitch !== void 0) attrs.push(`w:linePitch="${intAttr(dg.linePitch)}"`);
 	if (dg.charSpace !== void 0) attrs.push(`w:charSpace="${intAttr(dg.charSpace)}"`);
-	return attrs.length > 0 ? `<w:docGrid ${attrs.join(" ")}/>` : "";
+	return attrs.length > 0 ? `<w:docGrid ${attrs.join(" ")}/>` : "<w:docGrid/>";
 }
 function serializeOnOffElement(value, name) {
 	if (value === void 0) return "";
@@ -173,7 +174,7 @@ function serializeSectionProperties(props) {
 		serializeOnOffElement(props.noEndnote, "noEndnote"),
 		serializeOnOffElement(props.rtlGutter, "rtlGutter")
 	]) if (xml) parts.push(xml);
-	if (props.printerSettingsRelationshipId) parts.push(`<w:printerSettings r:id="${escapeXml(props.printerSettingsRelationshipId)}"/>`);
+	if (props.printerSettingsRelationshipId) parts.push(`<w:printerSettings r:id="${escapeXmlAttribute(props.printerSettingsRelationshipId)}"/>`);
 	for (const change of props.propertyChanges ?? []) parts.push(serializeSectionPropertyChange(change));
 	const unserializedChildNames = getUnserializedSectionPropertyChildNames(props);
 	if (unserializedChildNames && unserializedChildNames.length > 0) return "";

package/dist/docx/serializer/settingsSerializer.js

@@ -1,5 +1,6 @@
 import { serializePartElement } from "./partNamespaces.js";
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/settingsSerializer.ts
 const serializeSettingsXml = (settings) => {
 	const parts = [`<w:defaultTabStop w:val="${intAttr(settings.defaultTabStop)}"/>`];
@@ -7,8 +8,8 @@ const serializeSettingsXml = (settings) => {
 	if (settings.updateFields) parts.push("<w:updateFields w:val=\"true\"/>");
 	if (settings.themeFontLang) {
 		const attrs = [];
-		if (settings.themeFontLang.eastAsia) attrs.push(`w:eastAsia="${escapeXml(settings.themeFontLang.eastAsia)}"`);
-		if (settings.themeFontLang.bidi) attrs.push(`w:bidi="${escapeXml(settings.themeFontLang.bidi)}"`);
+		if (settings.themeFontLang.eastAsia) attrs.push(`w:eastAsia="${escapeXmlAttribute(settings.themeFontLang.eastAsia)}"`);
+		if (settings.themeFontLang.bidi) attrs.push(`w:bidi="${escapeXmlAttribute(settings.themeFontLang.bidi)}"`);
 		if (attrs.length > 0) parts.push(`<w:themeFontLang ${attrs.join(" ")}/>`);
 	}
 	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({

package/dist/docx/serializer/stylesSerializer.js

@@ -2,7 +2,7 @@ import { serializeParagraphFormatting } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTableCellFormatting, serializeTableFormatting, serializeTableRowFormatting } from "./tableSerializer.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/stylesSerializer.ts
 const serializeStylesXml = (definitions) => {
 	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
@@ -28,12 +28,12 @@ const serializeLatentStyles = (definitions) => {
 	return `<w:latentStyles${attrs.length > 0 ? ` ${attrs.join(" ")}` : ""}/>`;
 };
 const serializeStyle = (style) => {
-	const attrs = [`w:type="${style.type}"`, `w:styleId="${escapeXml(style.styleId)}"`];
+	const attrs = [`w:type="${style.type}"`, `w:styleId="${escapeXmlAttribute(style.styleId)}"`];
 	if (style.default) attrs.push("w:default=\"1\"");
-	const parts = [`<w:name w:val="${escapeXml(style.name ?? style.styleId)}"/>`];
-	if (style.basedOn) parts.push(`<w:basedOn w:val="${escapeXml(style.basedOn)}"/>`);
-	if (style.next) parts.push(`<w:next w:val="${escapeXml(style.next)}"/>`);
-	if (style.link) parts.push(`<w:link w:val="${escapeXml(style.link)}"/>`);
+	const parts = [`<w:name w:val="${escapeXmlAttribute(style.name ?? style.styleId)}"/>`];
+	if (style.basedOn) parts.push(`<w:basedOn w:val="${escapeXmlAttribute(style.basedOn)}"/>`);
+	if (style.next) parts.push(`<w:next w:val="${escapeXmlAttribute(style.next)}"/>`);
+	if (style.link) parts.push(`<w:link w:val="${escapeXmlAttribute(style.link)}"/>`);
 	if (style.uiPriority !== void 0) parts.push(`<w:uiPriority w:val="${style.uiPriority}"/>`);
 	pushBooleanElement(parts, "hidden", style.hidden);
 	pushBooleanElement(parts, "semiHidden", style.semiHidden);