@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/serializer/runSerializer.js

@@ -1,9 +1,14 @@
 import { isValidHexColor } from "../../utils/colorResolver.js";
-import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
+import { normalizeImageLuminancePercent } from "../../utils/imageLuminance.js";
+import { serializePreservedAttributes } from "../attributeRemainder.js";
+import { resolveEffectExtents, resolveWrapDistances, serializeAnchorAttributes, serializeEffectExtent, serializeInlineAttributes, serializeSimplePos, serializeWrapDistances } from "../drawingAnchor.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 { runHoldsPayload } from "../runPayload.js";
+import { requiredWrapPolygon, serializeWrapPolygon } from "../wrapPolygon.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializeTable } from "./tableSerializer.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
@@ -11,6 +16,7 @@ import { getSingularRunPropertyChange, serializeTrackedChangeAttributes } from "
 import { intAttr } from "./xmlUtils.js";
 import { panic } from "better-result";
 import { escapeXmlAttribute, escapeXmlText, requiresXmlSpacePreserve } from "@stll/docx-core";
+import { SCHEME_COLOR_VALUE_BY_THEME_COLOR, knownThemeColor, presetLineDashToken } from "@stll/docx-core/model";
 //#region src/docx/serializer/runSerializer.ts
 /**
 * Run Serializer - Serialize runs to OOXML XML
@@ -41,21 +47,13 @@ function getUniqueId(id) {
 	if (id !== void 0 && id !== "" && id !== 0) return String(id);
 	return String(nextAutoId++);
 }
-function extractRPrInner(rPrXml) {
-	if (!rPrXml.startsWith("<w:rPr>") || !rPrXml.endsWith("</w:rPr>")) return "";
-	return rPrXml.slice(7, -8);
-}
 function serializeRunPropertyChange(change) {
 	const previousRPrXml = serializeTextFormatting(change.previousFormatting) || "<w:rPr/>";
 	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}>${previousRPrXml}</w:rPrChange>`;
 }
 function serializeRunProperties(formatting, propertyChanges) {
-	const currentRPrXml = serializeTextFormatting(formatting);
-	const currentInner = currentRPrXml ? extractRPrInner(currentRPrXml) : "";
 	const propertyChange = getSingularRunPropertyChange(propertyChanges);
-	const combined = `${currentInner}${propertyChange ? serializeRunPropertyChange(propertyChange) : ""}`;
-	if (!combined) return "";
-	return `<w:rPr>${combined}</w:rPr>`;
+	return serializeTextFormatting(formatting, propertyChange ? [["rPrChange", serializeRunPropertyChange(propertyChange)]] : []);
 }
 /**
 * Serialize text content (w:t)
@@ -103,10 +101,7 @@ 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)
@@ -130,8 +125,10 @@ function serializeNoBreakHyphen(_content) {
 function serializeDrawingColor(color) {
 	if (!color) return "";
 	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]}"`;
+	const themeColor = color.themeColor && knownThemeColor(color.themeColor);
+	const schemeColor = themeColor ? SCHEME_COLOR_VALUE_BY_THEME_COLOR[themeColor] : null;
+	if (schemeColor !== null) {
+		let clr = `<a:schemeClr val="${schemeColor}"`;
 		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 += `/>`;
@@ -171,7 +168,7 @@ function serializeOutline(outline) {
 	if (outline.cap) attrs.push(`cap="${serializeLineCap(outline.cap)}"`);
 	const parts = [];
 	if (outline.color) parts.push(`<a:solidFill>${serializeDrawingColor(outline.color)}</a:solidFill>`);
-	if (outline.style) parts.push(`<a:prstDash val="${outline.style}"/>`);
+	if (outline.dash) parts.push(`<a:prstDash val="${escapeXmlAttribute(presetLineDashToken(outline.dash))}"/>`);
 	if (outline.join === "bevel") parts.push("<a:bevel/>");
 	else if (outline.join === "round") parts.push("<a:round/>");
 	else if (outline.join === "miter") parts.push("<a:miter/>");
@@ -195,20 +192,77 @@ function serializePosition(pos) {
 	parts.push("</wp:positionV>");
 	return parts.join("");
 }
+/**
+* The insets each `EG_WrapType` member's own type declares.
+*
+* Total over the wrap kinds, so a kind added to the model has to say which of
+* the four its element may carry. A key this map does not list cannot be
+* written on that element without failing the schema, whatever the drawing's
+* slots hold.
+*/
+const WRAP_CHILD_DISTANCE_KEYS = {
+	square: [
+		"distT",
+		"distB",
+		"distL",
+		"distR"
+	],
+	tight: ["distL", "distR"],
+	through: ["distL", "distR"],
+	topAndBottom: ["distT", "distB"],
+	behind: [],
+	inFront: [],
+	inline: []
+};
+/**
+* Which `EG_WrapType` members declare a `wp:effectExtent` of their own.
+*
+* Total over the wrap kinds for {@link WRAP_CHILD_DISTANCE_KEYS}'s reason: a
+* kind added to the model has to say whether its element may carry one, and
+* writing it where the type does not declare it fails the schema.
+*/
+const WRAP_CHILD_DECLARES_EFFECT_EXTENT = {
+	square: true,
+	tight: false,
+	through: false,
+	topAndBottom: true,
+	behind: false,
+	inFront: false,
+	inline: false
+};
 /** Serialize wrap type to wp:wrap* element */
-function serializeWrap(wrap) {
+function serializeWrap(wrap, effectExtent) {
 	const wrapText = wrap.wrapText ? ` wrapText="${wrap.wrapText}"` : " wrapText=\"bothSides\"";
+	const authored = resolveWrapDistances(wrap).wrapChild;
+	const distances = {};
+	for (const key of WRAP_CHILD_DISTANCE_KEYS[wrap.type]) {
+		const value = authored[key];
+		if (value !== void 0) distances[key] = value;
+	}
+	const dist = serializeWrapDistances(distances);
+	const extent = effectExtent !== void 0 && WRAP_CHILD_DECLARES_EFFECT_EXTENT[wrap.type] ? serializeEffectExtent(effectExtent) : "";
 	switch (wrap.type) {
-		case "square": return `<wp:wrapSquare${wrapText}/>`;
-		case "tight": return `<wp:wrapTight${wrapText}><wp:wrapPolygon edited="0"><wp:start x="0" y="0"/><wp:lineTo x="0" y="21600"/><wp:lineTo x="21600" y="21600"/><wp:lineTo x="21600" y="0"/><wp:lineTo x="0" y="0"/></wp:wrapPolygon></wp:wrapTight>`;
-		case "through": return `<wp:wrapThrough${wrapText}><wp:wrapPolygon edited="0"><wp:start x="0" y="0"/><wp:lineTo x="0" y="21600"/><wp:lineTo x="21600" y="21600"/><wp:lineTo x="21600" y="0"/><wp:lineTo x="0" y="0"/></wp:wrapPolygon></wp:wrapThrough>`;
-		case "topAndBottom": return "<wp:wrapTopAndBottom/>";
+		case "square": return extent ? `<wp:wrapSquare${wrapText}${dist}>${extent}</wp:wrapSquare>` : `<wp:wrapSquare${wrapText}${dist}/>`;
+		case "tight": return `<wp:wrapTight${wrapText}${dist}>${serializeWrapPolygon(requiredWrapPolygon(wrap.polygon))}</wp:wrapTight>`;
+		case "through": return `<wp:wrapThrough${wrapText}${dist}>${serializeWrapPolygon(requiredWrapPolygon(wrap.polygon))}</wp:wrapThrough>`;
+		case "topAndBottom": return extent ? `<wp:wrapTopAndBottom${dist}>${extent}</wp:wrapTopAndBottom>` : `<wp:wrapTopAndBottom${dist}/>`;
 		case "behind":
 		case "inFront": return "<wp:wrapNone/>";
 		case "inline": return "<wp:wrapNone/>";
 	}
 }
 /**
+* `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
@@ -220,25 +274,28 @@ function serializePicGraphic(image, imageRId, sharedId) {
 	const cy = image.size.height;
 	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 picNames = serializeNonVisualDrawingNames({
+		...image.pictureNames,
+		name: image.pictureNames?.name ?? image.filename ?? `image${id}`
+	});
+	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="${escapeXmlAttribute(name)}"${image.alt ? ` descr="${escapeXmlAttribute(image.alt)}"` : ""}/>`,
+		`<pic:cNvPr id="${id}"${picNames}/>`,
 		"<pic:cNvPicPr/>",
 		"</pic:nvPicPr>",
 		"<pic:blipFill>",
@@ -260,18 +317,6 @@ function serializePicGraphic(image, imageRId, sharedId) {
 	].join("");
 }
 /**
-* Serialize only authored wrap-distance attributes. OOXML defaults omitted
-* values to zero, but preserving absence keeps untouched models stable.
-*/
-function serializeWrapDistanceAttrs(wrap) {
-	const attrs = [];
-	if (wrap?.distT !== void 0) attrs.push(`distT="${intAttr(wrap.distT)}"`);
-	if (wrap?.distB !== void 0) attrs.push(`distB="${intAttr(wrap.distB)}"`);
-	if (wrap?.distL !== void 0) attrs.push(`distL="${intAttr(wrap.distL)}"`);
-	if (wrap?.distR !== void 0) attrs.push(`distR="${intAttr(wrap.distR)}"`);
-	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`
@@ -285,6 +330,23 @@ function serializeDocPrExtensions(image) {
 	return entries ? `<a:extLst>${entries}</a:extLst>` : "";
 }
 /**
+* Serialize `wp:docPr`'s two link children, in the order the schema declares.
+*
+* The click element is replayed from the source while the model still names the
+* target it named, which keeps `tooltip`, `tgtFrame`, `history` and the rest of
+* `CT_Hyperlink` that the model has no field for. A link the editor retargeted
+* no longer agrees with those bytes, so it is rebuilt from the target instead —
+* the alternative is writing a tooltip that points somewhere else. The hover
+* element has no modelled half to disagree with it, so it always replays.
+*/
+function serializeDocPrLinks(image) {
+	const hover = image.hlinkHoverXml ?? "";
+	const source = image.hlinkClickSource;
+	if (source !== void 0 && source.rId === image.hlinkRId) return `${source.xml}${hover}`;
+	if (image.hlinkRId === void 0) return hover;
+	return `<a:hlinkClick r:id="${escapeXmlAttribute(image.hlinkRId)}"/>${hover}`;
+}
+/**
 * Serialize drawing/image content (w:drawing) to full DrawingML XML
 */
 function serializeDrawingContent(content) {
@@ -292,19 +354,15 @@ function serializeDrawingContent(content) {
 	const isFloating = image.wrap.type !== "inline";
 	const cx = image.size.width;
 	const cy = image.size.height;
-	const wrapDistanceAttrs = serializeWrapDistanceAttrs(image.wrap);
-	const effL = image.padding?.left ?? 0;
-	const effT = image.padding?.top ?? 0;
-	const effR = image.padding?.right ?? 0;
-	const effB = image.padding?.bottom ?? 0;
-	const effectExtentEl = `<wp:effectExtent l="${intAttr(effL)}" t="${intAttr(effT)}" r="${intAttr(effR)}" b="${intAttr(effB)}"/>`;
+	const effectExtents = resolveEffectExtents(image.wrap, image.padding);
+	const effectExtentEl = serializeEffectExtent(effectExtents.drawing);
 	const docPrId = getUniqueId(image.id);
 	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 hlinkClick = serializeDocPrLinks(image);
 	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}/>`;
@@ -312,7 +370,7 @@ function serializeDrawingContent(content) {
 	const graphic = image.rId === void 0 ? "" : serializePicGraphic(image, image.rId, docPrId);
 	if (!isFloating) return [
 		"<w:drawing>",
-		`<wp:inline${wrapDistanceAttrs}>`,
+		`<wp:inline${serializeInlineAttributes(image.wrap)}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
 		docPr,
@@ -321,13 +379,16 @@ function serializeDrawingContent(content) {
 		"</wp:inline>",
 		"</w:drawing>"
 	].join("");
-	const behindDoc = image.wrap.type === "behind" ? "1" : "0";
 	const position = image.position ? serializePosition(image.position) : "<wp:positionH relativeFrom=\"column\"><wp:posOffset>0</wp:posOffset></wp:positionH><wp:positionV relativeFrom=\"paragraph\"><wp:posOffset>0</wp:posOffset></wp:positionV>";
-	const wrap = serializeWrap(image.wrap);
+	const wrap = serializeWrap(image.wrap, effectExtents.wrapChild);
 	return [
 		"<w:drawing>",
-		`<wp:anchor${wrapDistanceAttrs} simplePos="0" relativeHeight="251658240" behindDoc="${behindDoc}" locked="0" layoutInCell="${image.layoutInCell === false ? "0" : "1"}" allowOverlap="${image.allowOverlap === false ? "0" : "1"}">`,
-		"<wp:simplePos x=\"0\" y=\"0\"/>",
+		`<wp:anchor${serializeAnchorAttributes({
+			anchor: image.anchor,
+			wrap: image.wrap,
+			behindDoc: image.wrap.type === "behind"
+		})}>`,
+		serializeSimplePos(image.anchor),
 		position,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
@@ -366,20 +427,16 @@ function serializeShapeContent(content) {
 	const cy = shape.size.height;
 	const isTextBox = shape.shapeType === "textBox";
 	const isFloating = shape.wrap && shape.wrap.type !== "inline";
-	const wrapDistances = serializeWrapDistanceAttrs(shape.wrap);
 	const docPrId = getUniqueId(shape.id);
 	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\"";
-	if (shape.transform?.flipV) xfrmAttrs += " flipV=\"1\"";
+	const shapeNames = shape.shapeNames === void 0 ? "" : `<wps:cNvPr id="${docPrId}"${serializeNonVisualDrawingNames(shape.shapeNames)}/>`;
 	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>",
@@ -421,6 +478,7 @@ function serializeShapeContent(content) {
 		"<a:graphicData uri=\"http://schemas.microsoft.com/office/word/2010/wordprocessingShape\">",
 		[
 			"<wps:wsp>",
+			shapeNames,
 			`<wps:cNvSpPr${isTextBox ? " txBox=\"1\"" : ""}/>`,
 			spPr,
 			textBody === "" ? "<wps:bodyPr/>" : textBody,
@@ -429,28 +487,32 @@ function serializeShapeContent(content) {
 		"</a:graphicData>",
 		"</a:graphic>"
 	].join("");
+	const shapeEffectExtents = resolveEffectExtents(shape.wrap, shape.wrap?.effectExtentSlots?.drawing);
 	if (!isFloating) return [
 		"<w:drawing>",
-		`<wp:inline${wrapDistances}>`,
+		`<wp:inline${serializeInlineAttributes(shape.wrap)}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
-		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
+		serializeEffectExtent(shapeEffectExtents.drawing),
 		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
 		graphic,
 		"</wp:inline>",
 		"</w:drawing>"
 	].join("");
-	const behindDoc = shape.wrap?.type === "behind" ? "1" : "0";
 	const position = shape.position ? serializePosition(shape.position) : "<wp:positionH relativeFrom=\"column\"><wp:posOffset>0</wp:posOffset></wp:positionH><wp:positionV relativeFrom=\"paragraph\"><wp:posOffset>0</wp:posOffset></wp:positionV>";
 	if (!shape.wrap) panic("Floating shape must have a wrap property");
-	const wrap = serializeWrap(shape.wrap);
+	const wrap = serializeWrap(shape.wrap, shapeEffectExtents.wrapChild);
 	return [
 		"<w:drawing>",
-		`<wp:anchor${wrapDistances} simplePos="0" relativeHeight="251658240" behindDoc="${behindDoc}" locked="0" layoutInCell="1" allowOverlap="1">`,
-		"<wp:simplePos x=\"0\" y=\"0\"/>",
+		`<wp:anchor${serializeAnchorAttributes({
+			anchor: shape.anchor,
+			wrap: shape.wrap,
+			behindDoc: shape.wrap.type === "behind"
+		})}>`,
+		serializeSimplePos(shape.anchor),
 		position,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
-		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
+		serializeEffectExtent(shapeEffectExtents.drawing),
 		wrap,
 		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
@@ -475,6 +537,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);
@@ -489,6 +552,7 @@ function serializeRunContent(content) {
 * @returns XML string for the run
 */
 function serializeRun(run) {
+	if (!runHoldsPayload(run)) return "";
 	const parts = [];
 	const rPrXml = serializeRunProperties(run.formatting, run.propertyChanges);
 	if (rPrXml) parts.push(rPrXml);
@@ -496,7 +560,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
@@ -508,12 +573,6 @@ function serializeRuns(runs) {
 	return runs.map(serializeRun).join("");
 }
 /**
-* Check if a run has any content
-*/
-function hasRunContent(run) {
-	return run.content.length > 0;
-}
-/**
 * Check if a run has formatting
 */
 function hasRunFormatting(run) {
@@ -571,4 +630,4 @@ function createTabRun(formatting) {
 	};
 }
 //#endregion
-export { createBreakRun, createEmptyRun, createTabRun, createTextRun, getRunPlainText, hasRunContent, hasRunFormatting, resetAutoIdCounter, serializeRun, serializeRuns };
+export { createBreakRun, createEmptyRun, createTabRun, createTextRun, getRunPlainText, hasRunFormatting, resetAutoIdCounter, serializeRun, serializeRuns };

package/dist/docx/serializer/sdtPropertiesSerializer.d.ts

@@ -0,0 +1,26 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/serializer/sdtPropertiesSerializer.d.ts
+/**
+ * `<w:sdtPr>` from the model: the modelled children, the preserved ones, in
+ * schema order.
+ *
+ * An empty property set is written as an empty element rather than left out.
+ * `<w:sdtPr/>` and no `w:sdtPr` at all are different documents — the first is
+ * a richText control that states nothing, the second is markup the schema does
+ * not admit under `w:sdt` — and folio used to write the second for both.
+ */
+declare const serializeSdtProperties: (props: document_d_exports.SdtProperties) => string;
+/**
+ * `w:sdtEndPr`, replayed when the parse captured it and written from the
+ * record otherwise.
+ *
+ * The record's presence is the element's: `<w:sdtEndPr/>` with no `w:rPr` is
+ * what Word writes for most controls and differs from a missing element.
+ */
+declare const serializeSdtEndProperties: (properties: document_d_exports.SdtProperties) => string;
+/** `w:sdtPr` followed by `w:sdtEndPr`, in schema order. */
+declare const serializeSdtPropertyElements: (properties: document_d_exports.SdtProperties) => string;
+/** The one writer of an SDT wrapper at every content-model level. */
+declare const serializeSdtWrapper: (properties: document_d_exports.SdtProperties, contentXml: string) => string;
+//#endregion
+export { serializeSdtEndProperties, serializeSdtProperties, serializeSdtPropertyElements, serializeSdtWrapper };

package/dist/docx/serializer/sdtPropertiesSerializer.js

@@ -0,0 +1,111 @@
+import { statesControlKind } from "../sdtProperties.js";
+import { withModelledControlState } from "../sdtPropertiesPatch.js";
+import { serializeTextFormatting } from "./textFormattingSerializer.js";
+import { isSingleWellFormedElement } from "./xmlUtils.js";
+import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
+import { assertSafePreservedMarkup, serializeSequenceChildren } from "@stll/docx-core/schema";
+//#region src/docx/serializer/sdtPropertiesSerializer.ts
+/**
+* The one writer of `<w:sdtPr>`.
+*
+* Every content control — block, inline, row and cell — writes its property
+* set here. There used to be three producers: a fallback projection on the
+* block path, a second one on the inline path, and a regex pass over the
+* source's captured bytes that patched an interactive change back into them.
+* The three agreed on nothing in particular, and the patching pass existed
+* only because the replay was the serialization source.
+*
+* It is not any more. `parseSdtProperties` puts every child folio does not
+* model into `SdtProperties.preserved` at its `CT_SdtPr` ordinal, so the model
+* holds the whole element and the writer merges its two halves back in schema
+* order — which `CT_SdtPr` demands, and Word repairs a file that disregards.
+*/
+const listElement = (name, props) => {
+	return `<w:${name}${props.dropdownLastValue === void 0 ? "" : ` w:lastValue="${escapeXmlAttribute(props.dropdownLastValue)}"`}>${(props.listItems ?? []).map((item) => `<w:listItem w:displayText="${escapeXmlAttribute(item.displayText)}" w:value="${escapeXmlAttribute(item.value)}"/>`).join("")}</w:${name}>`;
+};
+/**
+* The kind marker for a control that carries none of its own.
+*
+* Only reached for a control built in code rather than parsed: a parsed one
+* keeps the element its author wrote, in the sink, glyph elements and all.
+* `richText` is the format's default and `unknown` is folio's word for a kind
+* it could not read, so neither writes a marker — a bare `w:sdtPr` already
+* means richText.
+*
+* A checkbox has no declared kind element at all: `w14:checkbox` is an
+* extension the Transitional content model does not know, so it is filed
+* under the slot the kind choice occupies, which is where Word writes it.
+*/
+const synthesizedKind = (props) => {
+	switch (props.sdtType) {
+		case "plainText": return ["text", "<w:text/>"];
+		case "date": return ["date", `<w:date${props.dateValueISO ? ` w:fullDate="${escapeXmlAttribute(props.dateValueISO)}"` : ""}>${props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttribute(props.dateFormat)}"/>` : ""}</w:date>`];
+		case "dropdown": return ["dropDownList", listElement("dropDownList", props)];
+		case "comboBox": return ["comboBox", listElement("comboBox", props)];
+		case "checkbox": return ["equation", `<w14:checkbox><w14:checked w14:val="${props.checked ? "1" : "0"}"/></w14:checkbox>`];
+		case "picture": return ["picture", "<w:picture/>"];
+		case "buildingBlockGallery": return ["docPartObj", "<w:docPartObj/>"];
+		case "group": return ["group", "<w:group/>"];
+		case "richText":
+		case "unknown": return ["richText", ""];
+		default: return props.sdtType;
+	}
+};
+/**
+* `<w:sdtPr>` from the model: the modelled children, the preserved ones, in
+* schema order.
+*
+* An empty property set is written as an empty element rather than left out.
+* `<w:sdtPr/>` and no `w:sdtPr` at all are different documents — the first is
+* a richText control that states nothing, the second is markup the schema does
+* not admit under `w:sdt` — and folio used to write the second for both.
+*/
+const serializeSdtProperties = (props) => {
+	assertSafePreservedMarkup(props.preserved);
+	const modelled = [];
+	if (props.alias !== void 0) modelled.push(["alias", `<w:alias w:val="${escapeXmlAttribute(props.alias)}"/>`]);
+	if (props.tag !== void 0) modelled.push(["tag", `<w:tag w:val="${escapeXmlAttribute(props.tag)}"/>`]);
+	if (props.id !== void 0) modelled.push(["id", `<w:id w:val="${props.id}"/>`]);
+	if (props.lock !== void 0) modelled.push(["lock", `<w:lock w:val="${props.lock}"/>`]);
+	if (props.placeholder !== void 0) modelled.push(["placeholder", `<w:placeholder><w:docPart w:val="${escapeXmlAttribute(props.placeholder)}"/></w:placeholder>`]);
+	if (props.showingPlaceholder !== void 0) modelled.push(["showingPlcHdr", serializeOnOffElement(props.showingPlaceholder, "showingPlcHdr")]);
+	const captured = props.preserved?.children ?? [];
+	let statedKind = false;
+	const preserved = captured.map((child) => {
+		if (!statesControlKind(child.xml)) return child;
+		statedKind = true;
+		return {
+			index: child.index,
+			xml: withModelledControlState(child.xml, props)
+		};
+	});
+	if (!statedKind) modelled.push(synthesizedKind(props));
+	const body = serializeSequenceChildren({
+		container: "content-control-properties",
+		modelled,
+		preserved: props.preserved === void 0 ? void 0 : { children: preserved }
+	}).join("");
+	return body.length === 0 ? "<w:sdtPr/>" : `<w:sdtPr>${body}</w:sdtPr>`;
+};
+/**
+* `w:sdtEndPr`, replayed when the parse captured it and written from the
+* record otherwise.
+*
+* The record's presence is the element's: `<w:sdtEndPr/>` with no `w:rPr` is
+* what Word writes for most controls and differs from a missing element.
+*/
+const serializeSdtEndProperties = (properties) => {
+	if (properties.rawEndPropertiesXml && isSingleWellFormedElement(properties.rawEndPropertiesXml, "sdtEndPr")) return properties.rawEndPropertiesXml;
+	const endProperties = properties.endProperties;
+	if (endProperties === void 0) return "";
+	const runProperties = serializeTextFormatting(endProperties.runProperties);
+	return runProperties.length > 0 ? `<w:sdtEndPr>${runProperties}</w:sdtEndPr>` : "<w:sdtEndPr/>";
+};
+/** `w:sdtPr` followed by `w:sdtEndPr`, in schema order. */
+const serializeSdtPropertyElements = (properties) => `${serializeSdtProperties(properties)}${serializeSdtEndProperties(properties)}`;
+/** The one writer of an SDT wrapper at every content-model level. */
+const serializeSdtWrapper = (properties, contentXml) => {
+	return `<w:sdt>${serializeSdtPropertyElements(properties)}${properties.rawSdtChildrenBeforeContent ?? ""}<w:sdtContent>${contentXml}</w:sdtContent>${properties.rawSdtChildrenAfterContent ?? ""}</w:sdt>`;
+};
+//#endregion
+export { serializeSdtEndProperties, serializeSdtProperties, serializeSdtPropertyElements, serializeSdtWrapper };