@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/selectiveXmlPatch.js

@@ -0,0 +1,493 @@
+//#region src/docx/selectiveXmlPatch.ts
+/**
+* Selective XML Patch Module
+*
+* Patches only changed paragraphs in document.xml, preserving
+* unchanged content byte-for-byte. Uses string offset tracking
+* with proper tag depth counting (not regex) to handle nested elements.
+*/
+/**
+* Whether `char` ends an element's tag name in XML — a whitespace separator
+* (space, tab, CR, or LF, all valid before attributes per XML 1.0 §3.1), the
+* tag close `>`, or a self-close `/`. Manual tag scanners must accept every
+* whitespace form, not just a literal space, so newline-formatted markup
+* (`<w:p\n  w14:paraId="…">`) is still recognized as the element rather than
+* mistaken for a longer-named sibling.
+*/
+function isXmlNameBoundary(char) {
+	return char === " " || char === "	" || char === "\n" || char === "\r" || char === ">" || char === "/";
+}
+/**
+* Find the exact string start and end offsets of a <w:p> element
+* identified by its w14:paraId attribute.
+*
+* Handles nested <w:p> elements (e.g. inside mc:AlternateContent)
+* via proper depth counting.
+*
+* Returns null if paraId not found or appears more than once (ambiguous).
+*/
+function findParagraphOffsets(xml, paraId) {
+	const escaped = escapeRegExp(paraId);
+	const pattern = new RegExp(`<w:p[\\s][^>]*w14:paraId="${escaped}"`, "gu");
+	const matches = [];
+	let match;
+	while ((match = pattern.exec(xml)) !== null) matches.push(match.index);
+	if (matches.length === 0) return null;
+	if (matches.length > 1) return null;
+	const start = matches[0];
+	let pos = start;
+	let depth = 0;
+	while (pos < xml.length) {
+		const tagStart = xml.indexOf("<", pos);
+		if (tagStart === -1) break;
+		if (xml.startsWith("<w:p", tagStart)) {
+			const charAfterTag = xml[tagStart + 4];
+			if (isXmlNameBoundary(charAfterTag)) {
+				const tagEnd = xml.indexOf(">", tagStart);
+				if (tagEnd === -1) break;
+				if (xml[tagEnd - 1] === "/") {
+					if (depth === 0) return {
+						start,
+						end: tagEnd + 1
+					};
+					pos = tagEnd + 1;
+				} else {
+					depth++;
+					pos = tagEnd + 1;
+				}
+			} else pos = tagStart + 1;
+		} else if (xml.startsWith("</w:p>", tagStart)) {
+			depth--;
+			if (depth === 0) return {
+				start,
+				end: tagStart + 6
+			};
+			pos = tagStart + 6;
+		} else pos = tagStart + 1;
+	}
+	return null;
+}
+/**
+* Extract the serialized XML for a specific paragraph by paraId
+* from a fully serialized document.xml string.
+*/
+function extractParagraphXml(serializedXml, paraId) {
+	const offsets = findParagraphOffsets(serializedXml, paraId);
+	if (!offsets) return null;
+	return serializedXml.slice(offsets.start, offsets.end);
+}
+/**
+* Count <w:p> elements in an XML string (top-level paragraph count).
+* Counts opening <w:p tags that are NOT self-closing.
+*/
+function countParagraphElements(xml) {
+	let count = 0;
+	const pattern = /<w:p[\s>]/gu;
+	let match;
+	while ((match = pattern.exec(xml)) !== null) {
+		const idx = match.index;
+		if (isXmlNameBoundary(xml[idx + 4])) count++;
+	}
+	return count;
+}
+/**
+* Find all paraIds in an XML string and return counts (to detect duplicates).
+*/
+function collectParaIds(xml) {
+	const ids = /* @__PURE__ */ new Map();
+	const pattern = /w14:paraId="(?<id>[^"]+)"/gu;
+	let match;
+	while ((match = pattern.exec(xml)) !== null) {
+		const id = match.groups["id"];
+		ids.set(id, (ids.get(id) ?? 0) + 1);
+	}
+	return ids;
+}
+/**
+* Validate that a selective patch can be safely applied.
+*
+* Checks:
+* - All changed paraIds exist in original XML (exactly once)
+* - All changed paraIds exist in serialized XML (exactly once)
+* - Paragraph count matches between original and serialized (unless disabled)
+*/
+function validatePatchSafety(originalXml, serializedXml, changedIds, options = {}) {
+	if (changedIds.size === 0) return { safe: true };
+	const originalParaIds = collectParaIds(originalXml);
+	const serializedParaIds = collectParaIds(serializedXml);
+	for (const id of changedIds) {
+		const origCount = originalParaIds.get(id) || 0;
+		if (origCount === 0) return {
+			safe: false,
+			reason: `paraId-not-found-in-original: ${id}`
+		};
+		if (origCount > 1) return {
+			safe: false,
+			reason: `duplicate-paraId-in-original: ${id}`
+		};
+	}
+	for (const id of changedIds) {
+		const serCount = serializedParaIds.get(id) || 0;
+		if (serCount === 0) return {
+			safe: false,
+			reason: `paraId-not-found-in-serialized: ${id}`
+		};
+		if (serCount > 1) return {
+			safe: false,
+			reason: `duplicate-paraId-in-serialized: ${id}`
+		};
+	}
+	if (options.checkParagraphCount === false) return { safe: true };
+	const originalCount = countParagraphElements(originalXml);
+	const serializedCount = countParagraphElements(serializedXml);
+	if (originalCount !== serializedCount) return {
+		safe: false,
+		reason: `paragraph-count-mismatch: original=${originalCount}, serialized=${serializedCount}`
+	};
+	return { safe: true };
+}
+/**
+* Build a patched document.xml by splicing new paragraph XML into
+* the original at the correct offsets. Only changed paragraphs
+* are replaced; everything else is preserved byte-for-byte.
+*
+* Returns null if any step fails.
+*/
+function buildPatchedDocumentXml(originalXml, serializedXml, changedIds) {
+	if (changedIds.size === 0) return originalXml;
+	if (!validatePatchSafety(originalXml, serializedXml, changedIds).safe) return null;
+	return spliceChangedParagraphs(originalXml, serializedXml, changedIds);
+}
+/**
+* Build a patched note part (word/footnotes.xml / word/endnotes.xml) by
+* splicing edited note paragraphs into the original, preserving unchanged
+* content byte-for-byte.
+*
+* Unlike {@link buildPatchedDocumentXml} this does NOT require the paragraph
+* counts to match: the document model only retains the normal notes, so the
+* serialized note XML omits the separator / continuationSeparator paragraphs
+* the original part still carries. Splicing by `paraId` keeps those separators
+* and every unedited note byte-exact while replacing only the edited ones.
+*
+* Returns null if any changed id is missing or ambiguous in either input, so
+* the caller can fall back to preserving the original part verbatim.
+*/
+function buildPatchedNoteXml(originalXml, serializedXml, changedIds) {
+	if (changedIds.size === 0) return originalXml;
+	if (!validatePatchSafety(originalXml, serializedXml, changedIds, { checkParagraphCount: false }).safe) return null;
+	return spliceChangedParagraphs(originalXml, serializedXml, changedIds);
+}
+/**
+* Replace each changed paragraph in `originalXml` with its re-serialized form
+* extracted from `serializedXml`, splicing end-to-start so earlier offsets stay
+* valid. Assumes safety has already been validated. Returns null if an offset
+* or extraction unexpectedly fails.
+*/
+function spliceChangedParagraphs(originalXml, serializedXml, changedIds) {
+	const replacements = [];
+	for (const paraId of changedIds) {
+		const origOffsets = findParagraphOffsets(originalXml, paraId);
+		if (!origOffsets) return null;
+		const newXml = extractParagraphXml(serializedXml, paraId);
+		if (!newXml) return null;
+		replacements.push({
+			start: origOffsets.start,
+			end: origOffsets.end,
+			newXml
+		});
+	}
+	replacements.sort((a, b) => b.start - a.start);
+	let result = originalXml;
+	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
+	return result;
+}
+/**
+* Depth-count the end of the element that opens at `start` (an `<openLiteral…>`
+* offset), returning its full range. Nested same-name opens increment depth;
+* the matching `closeTag` (or a self-close) at depth 0 ends it. The boundary
+* check skips longer-named siblings (`<w:numFmt>` when scanning `<w:num`).
+*/
+function scanElementRange(xml, start, openLiteral, closeTag) {
+	const afterOpenIndex = openLiteral.length;
+	let pos = start;
+	let depth = 0;
+	while (pos < xml.length) {
+		const tagStart = xml.indexOf("<", pos);
+		if (tagStart === -1) break;
+		if (xml.startsWith(openLiteral, tagStart)) {
+			if (!isXmlNameBoundary(xml[tagStart + afterOpenIndex])) {
+				pos = tagStart + 1;
+				continue;
+			}
+			const tagEnd = xml.indexOf(">", tagStart);
+			if (tagEnd === -1) break;
+			if (xml[tagEnd - 1] === "/") {
+				if (depth === 0) return {
+					start,
+					end: tagEnd + 1
+				};
+				pos = tagEnd + 1;
+			} else {
+				depth++;
+				pos = tagEnd + 1;
+			}
+		} else if (xml.startsWith(closeTag, tagStart)) {
+			depth--;
+			if (depth === 0) return {
+				start,
+				end: tagStart + closeTag.length
+			};
+			pos = tagStart + closeTag.length;
+		} else pos = tagStart + 1;
+	}
+	return null;
+}
+/**
+* Find the exact start/end offsets of the element `<openLiteral … idAttr="id">`,
+* depth-counting its matching close tag. Returns null when the id is absent or
+* ambiguous (appears more than once).
+*/
+function findElementByIdAttr(xml, openLiteral, closeTag, idAttr, id) {
+	const pattern = new RegExp(`${escapeRegExp(openLiteral)}[\\s][^>]*${escapeRegExp(idAttr)}="${escapeRegExp(id)}"`, "gu");
+	const matches = [];
+	let match;
+	while ((match = pattern.exec(xml)) !== null) matches.push(match.index);
+	if (matches.length !== 1) return null;
+	return scanElementRange(xml, matches[0], openLiteral, closeTag);
+}
+/**
+* Extract the serialized XML for `<openLiteral … idAttr="id">…`, or null when it
+* cannot be resolved uniquely.
+*/
+function extractElementByIdAttr(xml, openLiteral, closeTag, idAttr, id) {
+	const offsets = findElementByIdAttr(xml, openLiteral, closeTag, idAttr, id);
+	return offsets ? xml.slice(offsets.start, offsets.end) : null;
+}
+/**
+* The full range of the first `<openLiteral …>…</closeTag>` element, or null.
+* Used to locate an unkeyed sub-element (a level's `mc:AlternateContent`).
+*/
+function findFirstElement(xml, openLiteral, closeTag) {
+	let pos = 0;
+	while (pos < xml.length) {
+		const idx = xml.indexOf(openLiteral, pos);
+		if (idx === -1) return null;
+		if (isXmlNameBoundary(xml[idx + openLiteral.length])) return scanElementRange(xml, idx, openLiteral, closeTag);
+		pos = idx + 1;
+	}
+	return null;
+}
+/**
+* Collect the ids carried by opening `<openLiteral … idAttr="…">` tags, with
+* counts so duplicates can be rejected. The `[\s]` after the literal restricts
+* matches to the exact element (excluding `<w:numFmt` when scanning `<w:num`).
+*/
+function collectElementIds(xml, openLiteral, idAttr) {
+	const ids = /* @__PURE__ */ new Map();
+	const pattern = new RegExp(`${escapeRegExp(openLiteral)}[\\s][^>]*?${escapeRegExp(idAttr)}="(?<id>[^"]+)"`, "gu");
+	let match;
+	while ((match = pattern.exec(xml)) !== null) {
+		const id = match.groups["id"];
+		ids.set(id, (ids.get(id) ?? 0) + 1);
+	}
+	return ids;
+}
+const NUMBERING_OPEN_LITERAL = {
+	abstractNum: "<w:abstractNum",
+	num: "<w:num"
+};
+const NUMBERING_CLOSE_TAG = {
+	abstractNum: "</w:abstractNum>",
+	num: "</w:num>"
+};
+const NUMBERING_ID_ATTR = {
+	abstractNum: "w:abstractNumId",
+	num: "w:numId"
+};
+const LEVEL_OPEN_LITERAL = "<w:lvl";
+const LEVEL_CLOSE_TAG = "</w:lvl>";
+const LEVEL_ID_ATTR = "w:ilvl";
+function findNumberingElementOffsets(xml, kind, id) {
+	return findElementByIdAttr(xml, NUMBERING_OPEN_LITERAL[kind], NUMBERING_CLOSE_TAG[kind], NUMBERING_ID_ATTR[kind], id);
+}
+function extractNumberingElementXml(xml, kind, id) {
+	return extractElementByIdAttr(xml, NUMBERING_OPEN_LITERAL[kind], NUMBERING_CLOSE_TAG[kind], NUMBERING_ID_ATTR[kind], id);
+}
+function collectNumberingElementIds(xml, kind) {
+	return collectElementIds(xml, NUMBERING_OPEN_LITERAL[kind], NUMBERING_ID_ATTR[kind]);
+}
+const SYNTHETIC_NUM_FMT_PATTERN = /<w:numFmt w:val="decimalZero(?<width>[345])"\/>/u;
+/**
+* The numbering definitions whose current serialization differs from the
+* baseline (re-parsed original) serialization — the ones actually edited. An id
+* is only considered when it resolves uniquely in BOTH inputs, so a definition
+* added or removed relative to the original (which cannot be spliced by id) is
+* left out; both save paths defer those to the byte-exact original part.
+*/
+function collectChangedNumberingDefs(baselineXml, currentXml) {
+	const changedForKind = (kind) => {
+		const changed = /* @__PURE__ */ new Set();
+		const baselineIds = collectNumberingElementIds(baselineXml, kind);
+		for (const [id, count] of collectNumberingElementIds(currentXml, kind)) {
+			if (count !== 1 || baselineIds.get(id) !== 1) continue;
+			const before = extractNumberingElementXml(baselineXml, kind, id);
+			const after = extractNumberingElementXml(currentXml, kind, id);
+			if (before !== null && after !== null && before !== after) changed.add(id);
+		}
+		return changed;
+	};
+	return {
+		abstractNums: changedForKind("abstractNum"),
+		nums: changedForKind("num")
+	};
+}
+/**
+* The element representing a level's number format in the source XML: the
+* `<mc:AlternateContent>` block Word wraps a custom format in, else a
+* self-closing `<w:numFmt …/>` (covers `<w:numFmt w:val="custom" w:format=…/>`).
+*/
+function extractLevelNumFmtElement(levelXml) {
+	const alt = findFirstElement(levelXml, "<mc:AlternateContent", "</mc:AlternateContent>");
+	if (alt) return levelXml.slice(alt.start, alt.end);
+	const match = /<w:numFmt\b[^>]*\/>/u.exec(levelXml);
+	return match ? match[0] : null;
+}
+/**
+* A valid OOXML custom number format equivalent to a `decimalZero{width}`
+* synthetic value: a zero-padded first token folio's parser reads back to the
+* same width. Used only when the original element cannot be resolved, so a
+* changed definition never emits a non-OOXML synthetic value.
+*/
+function reconstructCustomNumFmt(width) {
+	return `<w:numFmt w:val="custom" w:format="${`${"0".repeat(Number.parseInt(width, 10) - 1)}1`}"/>`;
+}
+/**
+* The synthetic `decimalZero{width}` width the parser would derive from an
+* original level's number-format element (its custom `w:format` first token),
+* as the same digit-count string the SYNTHETIC_NUM_FMT_PATTERN captures. Mirrors
+* `parseCustomNumberFormat` (first comma-separated token, `^0+1$`, clamped to 5).
+* Returns null when the element carries no zero-padded custom format, so a
+* genuine format change is never mistaken for the original.
+*/
+function originalNumFmtWidth(numFmtElement) {
+	for (const match of numFmtElement.matchAll(/<w:numFmt\b[^>]*\/>/gu)) {
+		const tag = match[0];
+		if (!/\bw:val="custom"/u.test(tag)) continue;
+		const format = /\bw:format="(?<format>[^"]*)"/u.exec(tag)?.groups?.["format"];
+		if (format === void 0) continue;
+		const firstToken = format.split(",")[0]?.trim() ?? "";
+		return /^0+1$/u.test(firstToken) ? String(Math.min(firstToken.length, 5)) : null;
+	}
+	return null;
+}
+/**
+* Collect the `xmlns` / `xmlns:*` declarations from an element's opening tag
+* (the substring up to its first `>`).
+*/
+function collectXmlnsFromOpeningTag(elementXml) {
+	const out = {};
+	const tagEnd = elementXml.indexOf(">");
+	const openTag = tagEnd === -1 ? elementXml : elementXml.slice(0, tagEnd);
+	const pattern = /\s(?<name>xmlns(?::[\w.-]+)?)="(?<uri>[^"]*)"/gu;
+	let match;
+	while ((match = pattern.exec(openTag)) !== null) out[match.groups["name"]] = match.groups["uri"];
+	return out;
+}
+/**
+* Carry the given `xmlns` declarations onto `fragmentXml`'s root element so it
+* resolves every prefix even after the ancestor that declared them is replaced.
+* Declarations the fragment already carries win (mirrors the VML
+* `cloneWithXmlnsDeclarations` self-contained-clone behaviour, in the string
+* domain the byte-exact splice needs).
+*/
+function withXmlnsDeclarations(fragmentXml, xmlnsDecls) {
+	const own = collectXmlnsFromOpeningTag(fragmentXml);
+	const additions = Object.entries(xmlnsDecls).filter(([name]) => !(name in own)).map(([name, uri]) => ` ${name}="${uri}"`);
+	if (additions.length === 0) return fragmentXml;
+	let nameEnd = 1;
+	while (nameEnd < fragmentXml.length && !isXmlNameBoundary(fragmentXml[nameEnd])) nameEnd += 1;
+	return fragmentXml.slice(0, nameEnd) + additions.join("") + fragmentXml.slice(nameEnd);
+}
+/**
+* Swap each synthetic `decimalZero{3,4,5}` numFmt in a re-serialized definition
+* back to the original level's number-format element.
+*
+* folio's parser collapses a Word custom / mc:AlternateContent number format
+* into a synthetic `decimalZero{3,4,5}` value the model cannot re-emit as valid
+* OOXML. When an unrelated field of the definition is edited, the whole
+* definition is re-serialized, so without this pass the level's custom format
+* would be replaced by an invalid value and lost on reparse. For each level
+* whose re-emitted numFmt is synthetic, restore the original level's numFmt
+* element by ilvl ONLY when the model's synthetic value still matches the
+* original's (the format was not edited, just preserved past an unrelated
+* change). When the model deliberately changed the width (e.g. decimalZero4 ->
+* decimalZero5), or the original cannot be resolved, emit a valid OOXML custom
+* format for the CURRENT width instead — honoring the edit and never leaving a
+* synthetic value.
+*/
+function restoreLevelNumFmts(originalDefXml, currentDefXml) {
+	const replacements = [];
+	for (const [ilvl, count] of collectElementIds(currentDefXml, LEVEL_OPEN_LITERAL, LEVEL_ID_ATTR)) {
+		if (count !== 1) continue;
+		const curOffsets = findElementByIdAttr(currentDefXml, LEVEL_OPEN_LITERAL, LEVEL_CLOSE_TAG, LEVEL_ID_ATTR, ilvl);
+		if (!curOffsets) continue;
+		const curLevel = currentDefXml.slice(curOffsets.start, curOffsets.end);
+		const synthetic = SYNTHETIC_NUM_FMT_PATTERN.exec(curLevel);
+		if (!synthetic) continue;
+		const origLevel = extractElementByIdAttr(originalDefXml, LEVEL_OPEN_LITERAL, LEVEL_CLOSE_TAG, LEVEL_ID_ATTR, ilvl);
+		const currentWidth = synthetic.groups["width"];
+		const original = origLevel ? extractLevelNumFmtElement(origLevel) : null;
+		let replacement;
+		if (original && origLevel && originalNumFmtWidth(original) === currentWidth) replacement = withXmlnsDeclarations(original, {
+			...collectXmlnsFromOpeningTag(originalDefXml),
+			...collectXmlnsFromOpeningTag(origLevel)
+		});
+		else replacement = reconstructCustomNumFmt(currentWidth);
+		const restoredLevel = curLevel.slice(0, synthetic.index) + replacement + curLevel.slice(synthetic.index + synthetic[0].length);
+		replacements.push({
+			start: curOffsets.start,
+			end: curOffsets.end,
+			newXml: restoredLevel
+		});
+	}
+	replacements.sort((a, b) => b.start - a.start);
+	let result = currentDefXml;
+	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
+	return result;
+}
+/**
+* Build a patched `word/numbering.xml` by splicing the changed `w:abstractNum` /
+* `w:num` definitions from `currentXml` (the model's serialization) into
+* `originalXml`, preserving every other byte. Returns the original unchanged
+* when nothing changed, or null when a changed id cannot be resolved uniquely
+* in either input (so the caller preserves the original part verbatim).
+*/
+function buildPatchedNumberingXml(originalXml, currentXml, changed) {
+	if (changed.abstractNums.size === 0 && changed.nums.size === 0) return originalXml;
+	const replacements = [];
+	const collect = (kind, ids) => {
+		for (const id of ids) {
+			const origOffsets = findNumberingElementOffsets(originalXml, kind, id);
+			if (!origOffsets) return false;
+			const reserialized = extractNumberingElementXml(currentXml, kind, id);
+			if (reserialized === null) return false;
+			const newXml = restoreLevelNumFmts(originalXml.slice(origOffsets.start, origOffsets.end), reserialized);
+			replacements.push({
+				start: origOffsets.start,
+				end: origOffsets.end,
+				newXml
+			});
+		}
+		return true;
+	};
+	if (!collect("abstractNum", changed.abstractNums) || !collect("num", changed.nums)) return null;
+	replacements.sort((a, b) => b.start - a.start);
+	let result = originalXml;
+	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
+	return result;
+}
+function escapeRegExp(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+//#endregion
+export { buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, validatePatchSafety };

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

@@ -0,0 +1,6 @@
+import { document_d_exports } from "../../types/document.js";
+
+//#region src/docx/serializer/blockSdtSerializer.d.ts
+declare function serializeBlockSdt(blockSdt: document_d_exports.BlockSdt, serializeChild: (block: document_d_exports.BlockContent) => string): string;
+//#endregion
+export { serializeBlockSdt };

package/dist/docx/serializer/blockSdtSerializer.js

@@ -0,0 +1,88 @@
+import { reconcileRawSdtPr } from "../sdtPropertiesPatch.js";
+//#region src/docx/serializer/blockSdtSerializer.ts
+function escapeXmlAttr(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+function serializeFallbackSdtPr(props) {
+	const parts = [];
+	if (props.id !== void 0) parts.push(`<w:id w:val="${props.id}"/>`);
+	if (props.alias) parts.push(`<w:alias w:val="${escapeXmlAttr(props.alias)}"/>`);
+	if (props.tag) parts.push(`<w:tag w:val="${escapeXmlAttr(props.tag)}"/>`);
+	if (props.lock) parts.push(`<w:lock w:val="${props.lock}"/>`);
+	if (props.placeholder) parts.push(`<w:placeholder><w:docPart w:val="${escapeXmlAttr(props.placeholder)}"/></w:placeholder>`);
+	if (props.showingPlaceholder) parts.push("<w:showingPlcHdr/>");
+	switch (props.sdtType) {
+		case "plainText":
+			parts.push("<w:text/>");
+			break;
+		case "date": {
+			const fullDateAttr = props.dateValueISO ? ` w:fullDate="${escapeXmlAttr(props.dateValueISO)}"` : "";
+			const formatChild = props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttr(props.dateFormat)}"/>` : "";
+			if (fullDateAttr || formatChild) parts.push(`<w:date${fullDateAttr}>${formatChild}</w:date>`);
+			else parts.push("<w:date/>");
+			break;
+		}
+		case "dropdown":
+		case "comboBox": {
+			const tag = props.sdtType === "dropdown" ? "w:dropDownList" : "w:comboBox";
+			const items = (props.listItems ?? []).map((item) => `<w:listItem w:displayText="${escapeXmlAttr(item.displayText)}" w:value="${escapeXmlAttr(item.value)}"/>`).join("");
+			parts.push(`<${tag}>${items}</${tag}>`);
+			break;
+		}
+		case "checkbox": {
+			const val = props.checked ? "1" : "0";
+			parts.push(`<w14:checkbox><w14:checked w14:val="${val}"/></w14:checkbox>`);
+			break;
+		}
+		case "picture":
+			parts.push("<w:picture/>");
+			break;
+		case "buildingBlockGallery":
+			parts.push("<w:docPartObj/>");
+			break;
+		case "group":
+			parts.push("<w:group/>");
+			break;
+		default: break;
+	}
+	return `<w:sdtPr>${parts.join("")}</w:sdtPr>`;
+}
+function extractDropdownLastValue(blockSdt) {
+	if (blockSdt.properties.sdtType !== "dropdown" && blockSdt.properties.sdtType !== "comboBox") return;
+	const modeled = blockSdt.properties.dropdownLastValue;
+	if (modeled !== void 0) return modeled;
+	const firstBlock = blockSdt.content[0];
+	if (!firstBlock || firstBlock.type !== "paragraph") return;
+	const parts = [];
+	for (const child of firstBlock.content) if (child.type === "run") {
+		for (const item of child.content) if (item.type === "text") parts.push(item.text);
+	}
+	const text = parts.join("");
+	if (text.length === 0) return;
+	const items = blockSdt.properties.listItems;
+	if (items) {
+		const match = items.find((item) => item.displayText === text);
+		if (match) return match.value;
+	}
+	return text;
+}
+function extractDateFullDate(blockSdt) {
+	if (blockSdt.properties.sdtType !== "date") return;
+	const iso = blockSdt.properties.dateValueISO;
+	return iso !== void 0 && iso.length > 0 ? iso : void 0;
+}
+function serializeBlockSdt(blockSdt, serializeChild) {
+	const props = blockSdt.properties;
+	const baseSdtPr = props.rawPropertiesXml ?? serializeFallbackSdtPr(props);
+	const dateFullDate = extractDateFullDate(blockSdt);
+	const dropdownLastValue = extractDropdownLastValue(blockSdt);
+	const sdtPrXml = reconcileRawSdtPr(baseSdtPr, props, {
+		...dateFullDate !== void 0 ? { dateFullDate } : {},
+		...dropdownLastValue !== void 0 ? { dropdownLastValue } : {}
+	});
+	const sdtEndPrXml = props.rawEndPropertiesXml ?? "";
+	const contentXml = blockSdt.content.map(serializeChild).join("");
+	return `<w:sdt>${sdtPrXml}${sdtEndPrXml}${props.rawSdtChildrenBeforeContent ?? ""}<w:sdtContent>${contentXml}</w:sdtContent>${props.rawSdtChildrenAfterContent ?? ""}</w:sdt>`;
+}
+//#endregion
+export { serializeBlockSdt };

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

@@ -0,0 +1,25 @@
+import { document_d_exports } from "../../types/document.js";
+
+//#region src/docx/serializer/borderSerializer.d.ts
+/**
+ * Serialize a single border element (`<w:top .../>`, `<w:left .../>`, ...).
+ *
+ * `nil`/`none` mean "no border", but an *explicit* one overrides an inherited
+ * border (a table-level grid via `w:tblBorders`, a paragraph-style border, a
+ * section page border), so it must still round-trip as `<w:side w:val="nil"/>`.
+ * A `BorderSpec` only reaches here when the source set it or the user turned the
+ * border off, so emitting it is faithful, not noise — dropping it silently
+ * re-inherited the container default (e.g. hidden table gridlines reappeared as
+ * a full grid on reload). A `nil`/`none` side usually carries no
+ * size/color/space, but Word writes `w:sz="0" w:space="0" w:color="auto"` on a
+ * turned-off side; those are emitted when present so the value survives a
+ * save→parse round-trip and is not otherwise added.
+ *
+ * `style` and the color values come straight from the parsed DOCX (the parser
+ * casts `w:val`/`w:color` without validating the enum), so they are
+ * untrusted and are `escapeXml`'d before re-entering XML attributes; for valid
+ * documents these are enum/hex values, so escaping is a no-op.
+ */
+declare function serializeBorder(border: document_d_exports.BorderSpec | undefined, elementName: string): string;
+//#endregion
+export { serializeBorder };

package/dist/docx/serializer/borderSerializer.js

@@ -0,0 +1,44 @@
+import { escapeXml, intAttr } from "./xmlUtils.js";
+//#region src/docx/serializer/borderSerializer.ts
+/**
+* Serialize a single border element (`<w:top .../>`, `<w:left .../>`, ...).
+*
+* `nil`/`none` mean "no border", but an *explicit* one overrides an inherited
+* border (a table-level grid via `w:tblBorders`, a paragraph-style border, a
+* section page border), so it must still round-trip as `<w:side w:val="nil"/>`.
+* A `BorderSpec` only reaches here when the source set it or the user turned the
+* border off, so emitting it is faithful, not noise — dropping it silently
+* re-inherited the container default (e.g. hidden table gridlines reappeared as
+* a full grid on reload). A `nil`/`none` side usually carries no
+* size/color/space, but Word writes `w:sz="0" w:space="0" w:color="auto"` on a
+* turned-off side; those are emitted when present so the value survives a
+* save→parse round-trip and is not otherwise added.
+*
+* `style` and the color values come straight from the parsed DOCX (the parser
+* casts `w:val`/`w:color` without validating the enum), so they are
+* untrusted and are `escapeXml`'d before re-entering XML attributes; for valid
+* documents these are enum/hex values, so escaping is a no-op.
+*/
+function serializeBorder(border, elementName) {
+	if (!border) return "";
+	const attrs = [`w:val="${escapeXml(border.style)}"`];
+	if (border.size !== void 0) attrs.push(`w:sz="${intAttr(border.size)}"`);
+	if (border.space !== void 0) attrs.push(`w:space="${intAttr(border.space)}"`);
+	if (border.color) {
+		if (border.color.auto) attrs.push("w:color=\"auto\"");
+		else if (border.color.rgb) attrs.push(`w:color="${escapeXml(border.color.rgb)}"`);
+		if (border.color.themeColor) attrs.push(`w:themeColor="${escapeXml(border.color.themeColor)}"`);
+		if (border.color.themeTint) attrs.push(`w:themeTint="${escapeXml(border.color.themeTint)}"`);
+		if (border.color.themeShade) attrs.push(`w:themeShade="${escapeXml(border.color.themeShade)}"`);
+	}
+	if (border.shadow) attrs.push("w:shadow=\"true\"");
+	if (border.frame) attrs.push("w:frame=\"true\"");
+	if (border.artRelationshipId) attrs.push(`w:id="${escapeXml(border.artRelationshipId)}"`);
+	if (border.topLeftArtRelationshipId) attrs.push(`w:topLeft="${escapeXml(border.topLeftArtRelationshipId)}"`);
+	if (border.topRightArtRelationshipId) attrs.push(`w:topRight="${escapeXml(border.topRightArtRelationshipId)}"`);
+	if (border.bottomLeftArtRelationshipId) attrs.push(`w:bottomLeft="${escapeXml(border.bottomLeftArtRelationshipId)}"`);
+	if (border.bottomRightArtRelationshipId) attrs.push(`w:bottomRight="${escapeXml(border.bottomRightArtRelationshipId)}"`);
+	return `<w:${elementName} ${attrs.join(" ")}/>`;
+}
+//#endregion
+export { serializeBorder };