@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/serializer/paragraphSerializer.js

@@ -1,4 +1,6 @@
 import { modelParagraphFormattingEmission } from "../../internal/paragraphFormattingSerialization.js";
+import { serializePreservedAttributes } from "../attributeRemainder.js";
+import { fieldStateAttributes } from "../fieldState.js";
 import { getParagraphPropertySource, paragraphPropertySourceMatchesEmission } from "../paragraphPropertySource.js";
 import { reconcileRawSdtPr } from "../sdtPropertiesPatch.js";
 import { DATE_UTC_ATTRIBUTE } from "../trackedChangeInfo.js";
@@ -10,8 +12,9 @@ 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
 /**
@@ -331,25 +334,26 @@ 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. */
 function serializeHyperlinkChild(child, serializeChildRun) {
 	if (child.type === "run") return serializeChildRun(child);
-	return child.type === "bookmarkStart" ? serializeBookmarkStart(child) : serializeBookmarkEnd(child);
+	if (child.type === "bookmarkStart") return serializeBookmarkStart(child);
+	return child.type === "bookmarkEnd" ? serializeBookmarkEnd(child) : child.xml;
 }
 /**
 * Serialize a hyperlink (w:hyperlink)
 */
-function serializeHyperlink(hyperlink) {
-	const childrenXml = hyperlink.children.map((child) => serializeHyperlinkChild(child, serializeRun)).join("");
+function serializeHyperlink(hyperlink, disposition = "kept") {
+	const childrenXml = hyperlink.children.map((child) => serializeHyperlinkChild(child, (run) => serializeInlineRun(run, disposition))).join("");
 	return `<w:hyperlink${hyperlinkAttributes(hyperlink)}>${childrenXml}</w:hyperlink>`;
 }
 /**
@@ -366,10 +370,11 @@ function serializeBookmarkEnd(bookmark) {
 }
 /** Serialize a simple field without changing its authored OOXML field form. */
 function serializeSimpleField(field) {
-	const attrs = [`w:instr="${escapeXml(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("");
+	const attrs = [`w:instr="${escapeXmlAttribute(field.instruction)}"`, ...fieldStateAttributes(field)];
+	const contentXml = field.content.map((item) => {
+		if (item.type === "run") return serializeRun(item);
+		return item.type === "hyperlink" ? serializeHyperlink(item) : item.xml;
+	}).join("");
 	return `<w:fldSimple ${attrs.join(" ")}>${contentXml}</w:fldSimple>`;
 }
 /**
@@ -381,14 +386,12 @@ function serializeComplexField(field) {
 	const parts = [];
 	const structuralFormatting = field.formatting ?? field.fieldResult[0]?.formatting;
 	const rPrXml = structuralFormatting ? serializeTextFormatting(structuralFormatting) : "";
-	const beginAttrs = ["w:fldCharType=\"begin\""];
-	if (field.fldLock) beginAttrs.push("w:fldLock=\"true\"");
-	if (field.dirty) beginAttrs.push("w:dirty=\"true\"");
+	const beginAttrs = ["w:fldCharType=\"begin\"", ...fieldStateAttributes(field)];
 	parts.push(`<w:r>${rPrXml}<w:fldChar ${beginAttrs.join(" ")}/></w:r>`);
 	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)));
@@ -406,29 +409,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;
 		}
@@ -454,20 +457,22 @@ function synthesizeInlineSdtPr(props) {
 * the properties block was re-synthesized from the modeled projection alone,
 * silently dropping every unmodeled feature (and `w:sdtEndPr`) on save.
 */
-function serializeInlineSdt(sdt) {
+function serializeInlineSdt(sdt, disposition = "kept") {
 	const props = sdt.properties;
 	const contentXml = sdt.content.map((item) => {
 		switch (item.type) {
-			case "run": return serializeRun(item);
-			case "hyperlink": return serializeHyperlink(item);
+			case "run": return serializeInlineRun(item, disposition);
+			case "hyperlink": return serializeHyperlink(item, disposition);
 			case "simpleField": return serializeSimpleField(item);
 			case "complexField": return serializeComplexField(item);
-			case "inlineSdt": return serializeInlineSdt(item);
+			case "inlineSdt": return serializeInlineSdt(item, disposition);
+			case "inlineWrapper": return serializeParagraphContent(item, disposition);
 			case "insertion": return serializeTrackedChange("ins", item);
 			case "deletion": return serializeTrackedChange("del", item);
 			case "moveFrom": return serializeTrackedChange("moveFrom", item);
 			case "moveTo": return serializeTrackedChange("moveTo", item);
 			case "mathEquation": return item.ommlXml || "";
+			case "preservedInline": return item.xml;
 			default: return item;
 		}
 	}).join("");
@@ -488,6 +493,22 @@ function serializeMoveRangeStart(tag, marker) {
 function rewriteRunTextAsDeleted(xml) {
 	return xml.replace(/<w:t\b/gu, "<w:delText").replace(/<\/w:t>/gu, "</w:delText>").replace(/<w:instrText\b/gu, "<w:delInstrText").replace(/<\/w:instrText>/gu, "</w:delInstrText>");
 }
+function serializeDeletedRun(run) {
+	const xml = serializeRun(run);
+	if (!run.content.some((c) => c.type === "drawing" || c.type === "shape")) return rewriteRunTextAsDeleted(xml);
+	if (!run.content.some((c) => c.type !== "drawing" && c.type !== "shape")) return xml;
+	return run.content.map((content) => {
+		const contentXml = serializeRun({
+			...run,
+			content: [content]
+		});
+		if (content.type === "drawing" || content.type === "shape") return contentXml;
+		return rewriteRunTextAsDeleted(contentXml);
+	}).join("");
+}
+function serializeInlineRun(run, disposition) {
+	return disposition === "removed" ? serializeDeletedRun(run) : serializeRun(run);
+}
 function trackedChangeTag(change) {
 	switch (change.type) {
 		case "insertion": return "ins";
@@ -498,29 +519,28 @@ function trackedChangeTag(change) {
 }
 function serializeTrackedChange(tag, change) {
 	const attrs = serializeTrackedChangeAttributes(change.info);
-	const serializeDeletedRun = (run) => {
-		const xml = serializeRun(run);
-		if (!run.content.some((c) => c.type === "drawing" || c.type === "shape")) return rewriteRunTextAsDeleted(xml);
-		if (!run.content.some((c) => c.type !== "drawing" && c.type !== "shape")) return xml;
-		return run.content.map((content) => {
-			const contentXml = serializeRun({
-				...run,
-				content: [content]
-			});
-			if (content.type === "drawing" || content.type === "shape") return contentXml;
-			return rewriteRunTextAsDeleted(contentXml);
-		}).join("");
-	};
-	const serializeContentRun = (run) => tag === "del" || tag === "moveFrom" ? serializeDeletedRun(run) : serializeRun(run);
+	const disposition = tag === "del" || tag === "moveFrom" ? "removed" : "kept";
+	const serializeContentRun = (run) => serializeInlineRun(run, disposition);
 	const serializeWrappedItem = (item) => {
-		if (item.type === "run") return serializeContentRun(item);
-		if (item.type === "simpleField" || item.type === "complexField") {
-			const xml = item.type === "simpleField" ? serializeSimpleField(item) : serializeComplexField(item);
-			return tag === "del" || tag === "moveFrom" ? rewriteRunTextAsDeleted(xml) : xml;
+		switch (item.type) {
+			case "run": return serializeContentRun(item);
+			case "simpleField":
+			case "complexField": {
+				const xml = item.type === "simpleField" ? serializeSimpleField(item) : serializeComplexField(item);
+				return disposition === "removed" ? rewriteRunTextAsDeleted(xml) : xml;
+			}
+			case "mathEquation": return item.ommlXml;
+			case "insertion":
+			case "deletion":
+			case "moveFrom":
+			case "moveTo": return serializeTrackedChange(trackedChangeTag(item), item);
+			case "bookmarkStart": return serializeBookmarkStart(item);
+			case "bookmarkEnd": return serializeBookmarkEnd(item);
+			case "preservedInline": return item.xml;
+			case "inlineWrapper":
+			case "inlineSdt": return serializeParagraphContent(item, disposition);
+			default: return item;
 		}
-		if (item.type === "mathEquation") return item.ommlXml;
-		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") return serializeTrackedChange(trackedChangeTag(item), item);
-		return item.type === "bookmarkStart" ? serializeBookmarkStart(item) : serializeBookmarkEnd(item);
 	};
 	const open = `<w:${tag} ${attrs}>`;
 	const close = `</w:${tag}>`;
@@ -553,27 +573,22 @@ function serializeCommentReferenceRun(id) {
 /**
 * Serialize a single paragraph content item.
 *
-* `explicitCommentReferenceIds` holds the comment ids that already have their
-* own `commentReference` node in this paragraph (the parsed-from-Word shape).
-* For those, the `commentRangeEnd` marker must NOT also synthesize a reference
-* run, or a save→parse round-trip doubles the `<w:commentReference>`. The
-* editor (fromProseDoc) path emits range markers with no reference node, so the
-* synthetic run is still written when the id is absent from the set.
+* A `commentRangeEnd` writes an end and nothing else. Where the comment's
+* reference run goes is authored data the model carries as its own item, and
+* `completeCommentReferences` fills it in for a model that arrived without
+* one; a guess made here from one paragraph cannot see the rest of the story.
 */
-function serializeParagraphContent(content, explicitCommentReferenceIds) {
+function serializeParagraphContent(content, disposition = "kept") {
 	switch (content.type) {
-		case "run": return serializeRun(content);
-		case "hyperlink": return serializeHyperlink(content);
+		case "run": return serializeInlineRun(content, disposition);
+		case "hyperlink": return serializeHyperlink(content, disposition);
 		case "bookmarkStart": return serializeBookmarkStart(content);
 		case "bookmarkEnd": return serializeBookmarkEnd(content);
 		case "simpleField": return serializeSimpleField(content);
 		case "complexField": return serializeComplexField(content);
-		case "inlineSdt": return serializeInlineSdt(content);
+		case "inlineSdt": return serializeInlineSdt(content, disposition);
 		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 "commentRangeEnd": return `<w:commentRangeEnd ${markupRangeAttributes(content).join(" ")}/>`;
 		case "commentReference": return serializeCommentReferenceRun(content.id);
 		case "insertion": return serializeTrackedChange("ins", content);
 		case "deletion": return serializeTrackedChange("del", content);
@@ -583,11 +598,18 @@ function serializeParagraphContent(content, explicitCommentReferenceIds) {
 		case "moveFromRangeEnd": return `<w:moveFromRangeEnd ${markupRangeAttributes(content).join(" ")}/>`;
 		case "moveToRangeStart": return serializeMoveRangeStart("moveToRangeStart", content);
 		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="${escapeXml(content.direction)}"`}>${content.content.map((child) => serializeParagraphContent(child, explicitCommentReferenceIds)).join("")}</w:${tag}>`;
+		case "inlineWrapper": {
+			const inner = content.content.map((child) => serializeParagraphContent(child, disposition)).join("");
+			switch (content.kind) {
+				case "bidi": {
+					const tag = content.control === "override" ? "bdo" : "dir";
+					return `<w:${tag}${content.direction === void 0 ? "" : ` w:val="${escapeXmlAttribute(content.direction)}"`}>${inner}</w:${tag}>`;
+				}
+				default: return content.kind;
+			}
 		}
 		case "mathEquation": return content.ommlXml || "";
+		case "preservedInline": return content.xml;
 		default: return "";
 	}
 }
@@ -600,21 +622,20 @@ 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(" ")}` : "";
+	const written = serializePreservedAttributes(attrs, paragraph.preservedAttributes);
+	const attrsStr = written.length > 0 ? ` ${written.join(" ")}` : "";
 	parts.push(serializeParagraphFormattingWithOptions(paragraph.formatting, {
 		propertyChanges: paragraph.propertyChanges,
 		paragraphMarkChange: paragraph.pPrMark,
 		propertySource: getParagraphPropertySource(paragraph),
 		sectionProperties: paragraph.sectionProperties
 	}));
-	const explicitCommentReferenceIds = /* @__PURE__ */ new Set();
-	for (const content of paragraph.content) if (content.type === "commentReference") explicitCommentReferenceIds.add(content.id);
 	let pendingRenderedPageBreak = paragraph.renderedPageBreakBefore === true;
 	for (const content of paragraph.content) {
-		let contentXml = serializeParagraphContent(content, explicitCommentReferenceIds);
+		let contentXml = serializeParagraphContent(content);
 		if (contentXml) {
 			if (pendingRenderedPageBreak) {
 				const next = injectRenderedPageBreakIntoFirstRun(contentXml);

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,19 @@
 import { isValidHexColor } from "../../utils/colorResolver.js";
+import { normalizeImageLuminancePercent } from "../../utils/imageLuminance.js";
+import { serializePreservedAttributes } from "../attributeRemainder.js";
 import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
+import { fieldStateAttributes } from "../fieldState.js";
 import { serializeGraphicFrameLocks } from "../graphicFrameLocks.js";
+import { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE } from "../imageParser.js";
 import { canReplayEditableImageRawXml } from "../imageRawXml.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 { requiresXmlSpacePreserve } from "@stll/docx-core";
+import { escapeXmlAttribute, escapeXmlText, requiresXmlSpacePreserve } from "@stll/docx-core";
 //#region src/docx/serializer/runSerializer.ts
 /**
 * Run Serializer - Serialize runs to OOXML XML
@@ -59,7 +64,7 @@ function serializeRunProperties(formatting, propertyChanges) {
 * Serialize text content (w:t)
 */
 function serializeTextContent(content) {
-	return `<w:t${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 +72,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 +93,7 @@ function serializeBreakContent(content) {
 * Serialize symbol content (w:sym)
 */
 function serializeSymbolContent(content) {
-	return `<w:sym${content.font === "" ? "" : ` w:font="${escapeXml(content.font)}"`}${content.char === "" ? "" : ` 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
@@ -101,16 +106,13 @@ function serializeNoteReference(content) {
 * Serialize field character (w:fldChar)
 */
 function serializeFieldChar(content) {
-	const attrs = [`w:fldCharType="${content.charType}"`];
-	if (content.fldLock) attrs.push("w:fldLock=\"true\"");
-	if (content.dirty) attrs.push("w:dirty=\"true\"");
-	return `<w:fldChar ${attrs.join(" ")}/>`;
+	return `<w:fldChar ${[`w:fldCharType="${content.charType}"`, ...fieldStateAttributes(content)].join(" ")}/>`;
 }
 /**
 * 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;
 	}
@@ -207,6 +209,17 @@ function serializeWrap(wrap) {
 	}
 }
 /**
+* `a:xfrm` attributes for an authored transform.
+*
+* Written iff authored: `rot="0"` and `flipH="0"` are OOXML's defaults, so a
+* truthiness guard cannot tell "the author said none" from "the author said
+* nothing", and a save erased an authored zero.
+*/
+const serializeTransformAttrs = (transform) => {
+	if (transform === void 0) return "";
+	return `${transform.rotation === void 0 ? "" : ` rot="${Math.round(transform.rotation * 6e4)}"`}${transform.flipH === void 0 ? "" : ` flipH="${transform.flipH ? 1 : 0}"`}${transform.flipV === void 0 ? "" : ` flipV="${transform.flipV ? 1 : 0}"`}`;
+};
+/**
 * Build the common a:graphic > pic:pic element for images.
 *
 * Takes the relationship id as a separate argument so the caller has to have
@@ -216,27 +229,27 @@ function serializeWrap(wrap) {
 function serializePicGraphic(image, imageRId, sharedId) {
 	const cx = image.size.width;
 	const cy = image.size.height;
-	const rId = escapeXml(imageRId);
+	const rId = escapeXmlAttribute(imageRId);
 	const id = sharedId;
 	const name = image.filename || `image${id}`;
-	let xfrmAttrs = "";
-	if (image.transform?.rotation) xfrmAttrs += ` rot="${Math.round(image.transform.rotation * 6e4)}"`;
-	if (image.transform?.flipH) xfrmAttrs += " flipH=\"1\"";
-	if (image.transform?.flipV) xfrmAttrs += " flipV=\"1\"";
+	const xfrmAttrs = serializeTransformAttrs(image.transform);
 	const cropAttrs = [];
 	if (image.crop?.left) cropAttrs.push(`l="${Math.round(image.crop.left * 1e5)}"`);
 	if (image.crop?.top) cropAttrs.push(`t="${Math.round(image.crop.top * 1e5)}"`);
 	if (image.crop?.right) cropAttrs.push(`r="${Math.round(image.crop.right * 1e5)}"`);
 	if (image.crop?.bottom) cropAttrs.push(`b="${Math.round(image.crop.bottom * 1e5)}"`);
 	const srcRectEl = cropAttrs.length > 0 ? `<a:srcRect ${cropAttrs.join(" ")}/>` : "";
-	const alphaChild = image.opacity !== void 0 && image.opacity < 1 ? `<a:alphaModFix amt="${Math.round(Math.max(0, image.opacity) * 1e5)}"/>` : "";
-	const blipEl = alphaChild ? `<a:blip r:embed="${rId}">${alphaChild}</a:blip>` : `<a:blip r:embed="${rId}"/>`;
+	const luminanceAttrs = [];
+	if (image.effects?.brightness !== void 0 && Number.isFinite(image.effects.brightness)) luminanceAttrs.push(`bright="${Math.round(normalizeImageLuminancePercent(image.effects.brightness) * 1e3)}"`);
+	if (image.effects?.contrast !== void 0 && Number.isFinite(image.effects.contrast)) luminanceAttrs.push(`contrast="${Math.round(normalizeImageLuminancePercent(image.effects.contrast) * 1e3)}"`);
+	const blipChildren = `${luminanceAttrs.length === 0 ? "" : `<a:lum ${luminanceAttrs.join(" ")}/>`}${image.opacity !== void 0 && image.opacity < 1 ? `<a:alphaModFix amt="${Math.round(Math.max(0, image.opacity) * 1e5)}"/>` : ""}`;
+	const blipEl = blipChildren ? `<a:blip r:embed="${rId}">${blipChildren}</a:blip>` : `<a:blip r:embed="${rId}"/>`;
 	return [
 		"<a:graphic xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\">",
 		"<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>",
@@ -270,6 +283,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) {
@@ -284,14 +310,15 @@ 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 = image.rId === void 0 ? "" : serializePicGraphic(image, image.rId, docPrId);
 	if (!isFloating) return [
@@ -299,7 +326,7 @@ function serializeDrawingContent(content) {
 		`<wp:inline${wrapDistanceAttrs}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
-		inlineDocPr,
+		docPr,
 		graphicFramePr,
 		graphic,
 		"</wp:inline>",
@@ -316,7 +343,7 @@ function serializeDrawingContent(content) {
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
 		wrap,
-		anchorDocPr,
+		docPr,
 		graphicFramePr,
 		graphic,
 		"</wp:anchor>",
@@ -339,7 +366,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)
@@ -352,14 +379,14 @@ 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}`);
-	let xfrmAttrs = "";
-	if (shape.transform?.rotation) xfrmAttrs += ` rot="${Math.round(shape.transform.rotation * 6e4)}"`;
-	if (shape.transform?.flipH) xfrmAttrs += " flipH=\"1\"";
-	if (shape.transform?.flipV) xfrmAttrs += " flipV=\"1\"";
+	const docPrNames = serializeNonVisualDrawingNames({
+		...shape.name !== void 0 ? { name: shape.name } : {},
+		...shape.alt !== void 0 ? { alt: shape.alt } : {},
+		...shape.title !== void 0 ? { title: shape.title } : {}
+	});
 	const spPr = [
 		"<wps:spPr>",
-		`<a:xfrm${xfrmAttrs}>`,
+		`<a:xfrm${serializeTransformAttrs(shape.transform)}>`,
 		"<a:off x=\"0\" y=\"0\"/>",
 		`<a:ext cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		"</a:xfrm>",
@@ -386,7 +413,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>",
@@ -414,7 +441,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>",
@@ -432,7 +459,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>",
@@ -455,6 +482,7 @@ function serializeRunContent(content) {
 		case "softHyphen": return serializeSoftHyphen(content);
 		case "noBreakHyphen": return serializeNoBreakHyphen(content);
 		case "renderedPageBreak": return "<w:lastRenderedPageBreak/>";
+		case "preservedXml": return content.xml;
 		case "drawing":
 			if (content.rawXml && canReplayEditableImageRawXml(content)) return content.rawXml;
 			return serializeDrawingContent(content);
@@ -476,7 +504,8 @@ function serializeRun(run) {
 		const contentXml = serializeRunContent(content);
 		if (contentXml) parts.push(contentXml);
 	}
-	return `<w:r>${parts.join("")}</w:r>`;
+	const attrs = serializePreservedAttributes([], run.preservedAttributes);
+	return `<w:r${attrs.length > 0 ? ` ${attrs.join(" ")}` : ""}>${parts.join("")}</w:r>`;
 }
 /**
 * Serialize multiple runs to OOXML XML