@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/serializer/textFormattingSerializer.js

@@ -1,8 +1,11 @@
 import { HIGHLIGHT_COLOR_VALUES } from "../../types/documentEnumValues.js";
 import { isValidHexColor } from "../../utils/colorResolver.js";
 import { roundHorizontalScalePercentForSerialization } from "../../utils/horizontalScale.js";
+import { serializePreservedAttributes } from "../attributeRemainder.js";
 import { intAttr } from "./xmlUtils.js";
-import { escapeXmlAttribute } from "@stll/docx-core";
+import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
+import { themeColorToken } from "@stll/docx-core/model";
+import { serializeSequenceChildren } from "@stll/docx-core/schema";
 //#region src/docx/serializer/textFormattingSerializer.ts
 const VALID_HIGHLIGHT_COLORS = new Set(HIGHLIGHT_COLOR_VALUES);
 /**
@@ -14,7 +17,7 @@ function serializeColorElement(color) {
 	const attrs = [];
 	if (auto) attrs.push("w:val=\"auto\"");
 	else if (rgb && isValidHexColor(rgb)) attrs.push(`w:val="${escapeXmlAttribute(rgb)}"`);
-	if (themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColor)}"`);
+	if (themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColorToken(themeColor))}"`);
 	if (themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(themeTint)}"`);
 	if (themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(themeShade)}"`);
 	return attrs.length === 0 ? "" : `<w:color ${attrs.join(" ")}/>`;
@@ -24,122 +27,129 @@ function serializeColorElement(color) {
 */
 function serializeShading(shading) {
 	if (!shading) return "";
-	const { pattern, color, fill } = shading;
+	const { pattern, color, fill, preservedAttributes } = shading;
 	const attrs = [];
 	if (pattern) attrs.push(`w:val="${escapeXmlAttribute(pattern)}"`);
 	else attrs.push("w:val=\"clear\"");
 	if (color) {
-		const { rgb, auto, themeColor: _themeColor, themeTint: _themeTint, themeShade: _themeShade } = color;
+		const { rgb, auto, themeColor, themeTint, themeShade } = color;
 		if (rgb && isValidHexColor(rgb)) attrs.push(`w:color="${escapeXmlAttribute(rgb)}"`);
 		else if (auto) attrs.push("w:color=\"auto\"");
+		if (themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColorToken(themeColor))}"`);
+		if (themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(themeTint)}"`);
+		if (themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(themeShade)}"`);
 	}
 	if (fill) {
 		const { rgb, auto, themeColor, themeTint, themeShade } = fill;
 		if (rgb && isValidHexColor(rgb)) attrs.push(`w:fill="${escapeXmlAttribute(rgb)}"`);
 		else if (auto) attrs.push("w:fill=\"auto\"");
-		if (themeColor) attrs.push(`w:themeFill="${escapeXmlAttribute(themeColor)}"`);
+		if (themeColor) attrs.push(`w:themeFill="${escapeXmlAttribute(themeColorToken(themeColor))}"`);
 		if (themeTint) attrs.push(`w:themeFillTint="${escapeXmlAttribute(themeTint)}"`);
 		if (themeShade) attrs.push(`w:themeFillShade="${escapeXmlAttribute(themeShade)}"`);
 	}
-	return attrs.length === 0 ? "" : `<w:shd ${attrs.join(" ")}/>`;
+	const written = serializePreservedAttributes(attrs, preservedAttributes);
+	return written.length === 0 ? "" : `<w:shd ${written.join(" ")}/>`;
 }
+const numberTag = (name, value) => value === void 0 ? "" : `<w:${name} w:val="${intAttr(value)}"/>`;
+const serializeFontFamily = (fontFamily) => {
+	if (!fontFamily) return "";
+	const { ascii, hAnsi, eastAsia, cs: complexScript, hint, asciiTheme, hAnsiTheme, eastAsiaTheme, csTheme } = fontFamily;
+	const attrs = [];
+	if (ascii) attrs.push(`w:ascii="${escapeXmlAttribute(ascii)}"`);
+	if (hAnsi) attrs.push(`w:hAnsi="${escapeXmlAttribute(hAnsi)}"`);
+	if (eastAsia) attrs.push(`w:eastAsia="${escapeXmlAttribute(eastAsia)}"`);
+	if (complexScript) attrs.push(`w:cs="${escapeXmlAttribute(complexScript)}"`);
+	if (hint) attrs.push(`w:hint="${escapeXmlAttribute(hint)}"`);
+	if (asciiTheme) attrs.push(`w:asciiTheme="${escapeXmlAttribute(asciiTheme)}"`);
+	if (hAnsiTheme) attrs.push(`w:hAnsiTheme="${escapeXmlAttribute(hAnsiTheme)}"`);
+	if (eastAsiaTheme) attrs.push(`w:eastAsiaTheme="${escapeXmlAttribute(eastAsiaTheme)}"`);
+	if (csTheme) attrs.push(`w:cstheme="${escapeXmlAttribute(csTheme)}"`);
+	return attrs.length === 0 ? "" : `<w:rFonts ${attrs.join(" ")}/>`;
+};
+const serializeUnderline = (underline) => {
+	if (!underline) return "";
+	const { style, color } = underline;
+	const attrs = [`w:val="${style}"`];
+	if (color) {
+		const { rgb, themeColor, themeTint, themeShade, auto: _auto } = color;
+		if (rgb && isValidHexColor(rgb)) attrs.push(`w:color="${escapeXmlAttribute(rgb)}"`);
+		if (themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColorToken(themeColor))}"`);
+		if (themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(themeTint)}"`);
+		if (themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(themeShade)}"`);
+	}
+	return `<w:u ${attrs.join(" ")}/>`;
+};
+const serializeLanguage = (language) => {
+	if (!language) return "";
+	const { val, eastAsia, bidi } = language;
+	const attrs = [];
+	if (val) attrs.push(`w:val="${escapeXmlAttribute(val)}"`);
+	if (eastAsia) attrs.push(`w:eastAsia="${escapeXmlAttribute(eastAsia)}"`);
+	if (bidi) attrs.push(`w:bidi="${escapeXmlAttribute(bidi)}"`);
+	return attrs.length === 0 ? "" : `<w:lang ${attrs.join(" ")}/>`;
+};
 /**
-* Serialize text formatting properties to w:rPr XML
+* The single `w:rPr` writer.
+*
+* A run, the paragraph mark, a style, a numbering level and the snapshot
+* inside either kind of `w:rPrChange` all write their run properties through
+* here, so none of them can grow its own order or its own idea of which
+* children exist. `EG_RPrBase` is an `xsd:choice` referenced
+* `maxOccurs="unbounded"`, so a `w:rPr` in any order is valid and the order
+* below is a canonical form rather than a validity rule: it is the one Word
+* writes, and writing it from the generated declared-child list is what stops
+* two of folio's serializers from disagreeing. The restatement is what
+* drifted, and it is why folio wrote `w:vanish` before `w:noProof` while the
+* schema declares the reverse.
+*
+* @param owned children a sibling record holds; see {@link OwnedRunPropertyChild}
 */
-function serializeTextFormatting(input) {
-	if (!input) return "";
-	const { bold, boldCs, italic, italicCs, underline, strike, doubleStrike, vertAlign, smallCaps, allCaps, hidden, noProof, color, highlight, shading, fontSize, fontSizeCs, fontFamily, language, spacing, position, scale, kerning, effect, emphasisMark, emboss, imprint, outline, shadow, rtl, cs, styleId } = input;
-	const parts = [];
-	if (styleId) parts.push(`<w:rStyle w:val="${escapeXmlAttribute(styleId)}"/>`);
-	if (fontFamily) {
-		const { ascii, hAnsi, eastAsia, cs: complexScript, hint, asciiTheme, hAnsiTheme, eastAsiaTheme, csTheme } = fontFamily;
-		const fontAttrs = [];
-		if (ascii) fontAttrs.push(`w:ascii="${escapeXmlAttribute(ascii)}"`);
-		if (hAnsi) fontAttrs.push(`w:hAnsi="${escapeXmlAttribute(hAnsi)}"`);
-		if (eastAsia) fontAttrs.push(`w:eastAsia="${escapeXmlAttribute(eastAsia)}"`);
-		if (complexScript) fontAttrs.push(`w:cs="${escapeXmlAttribute(complexScript)}"`);
-		if (hint) fontAttrs.push(`w:hint="${escapeXmlAttribute(hint)}"`);
-		if (asciiTheme) fontAttrs.push(`w:asciiTheme="${escapeXmlAttribute(asciiTheme)}"`);
-		if (hAnsiTheme) fontAttrs.push(`w:hAnsiTheme="${escapeXmlAttribute(hAnsiTheme)}"`);
-		if (eastAsiaTheme) fontAttrs.push(`w:eastAsiaTheme="${escapeXmlAttribute(eastAsiaTheme)}"`);
-		if (csTheme) fontAttrs.push(`w:cstheme="${escapeXmlAttribute(csTheme)}"`);
-		if (fontAttrs.length > 0) parts.push(`<w:rFonts ${fontAttrs.join(" ")}/>`);
-	}
-	if (bold === true) parts.push("<w:b/>");
-	else if (bold === false) parts.push("<w:b w:val=\"0\"/>");
-	if (boldCs === true) parts.push("<w:bCs/>");
-	else if (boldCs === false) parts.push("<w:bCs w:val=\"0\"/>");
-	if (italic === true) parts.push("<w:i/>");
-	else if (italic === false) parts.push("<w:i w:val=\"0\"/>");
-	if (italicCs === true) parts.push("<w:iCs/>");
-	else if (italicCs === false) parts.push("<w:iCs w:val=\"0\"/>");
-	if (allCaps === true) parts.push("<w:caps/>");
-	else if (allCaps === false) parts.push("<w:caps w:val=\"0\"/>");
-	if (smallCaps === true) parts.push("<w:smallCaps/>");
-	else if (smallCaps === false) parts.push("<w:smallCaps w:val=\"0\"/>");
-	if (strike === true) parts.push("<w:strike/>");
-	else if (strike === false) parts.push("<w:strike w:val=\"0\"/>");
-	if (doubleStrike === true) parts.push("<w:dstrike/>");
-	else if (doubleStrike === false) parts.push("<w:dstrike w:val=\"0\"/>");
-	if (outline === true) parts.push("<w:outline/>");
-	else if (outline === false) parts.push("<w:outline w:val=\"0\"/>");
-	if (shadow === true) parts.push("<w:shadow/>");
-	else if (shadow === false) parts.push("<w:shadow w:val=\"0\"/>");
-	if (emboss === true) parts.push("<w:emboss/>");
-	else if (emboss === false) parts.push("<w:emboss w:val=\"0\"/>");
-	if (imprint === true) parts.push("<w:imprint/>");
-	else if (imprint === false) parts.push("<w:imprint w:val=\"0\"/>");
-	if (hidden === true) parts.push("<w:vanish/>");
-	else if (hidden === false) parts.push("<w:vanish w:val=\"0\"/>");
-	if (noProof === true) parts.push("<w:noProof/>");
-	else if (noProof === false) parts.push("<w:noProof w:val=\"0\"/>");
-	const colorXml = serializeColorElement(color);
-	if (colorXml) parts.push(colorXml);
-	if (spacing !== void 0) parts.push(`<w:spacing w:val="${intAttr(spacing)}"/>`);
-	const horizontalScale = roundHorizontalScalePercentForSerialization(scale);
-	if (horizontalScale !== void 0) parts.push(`<w:w w:val="${intAttr(horizontalScale)}"/>`);
-	if (kerning !== void 0) parts.push(`<w:kern w:val="${intAttr(kerning)}"/>`);
-	if (position !== void 0) parts.push(`<w:position w:val="${intAttr(position)}"/>`);
-	if (fontSize !== void 0) parts.push(`<w:sz w:val="${intAttr(fontSize)}"/>`);
-	if (fontSizeCs !== void 0) parts.push(`<w:szCs w:val="${intAttr(fontSizeCs)}"/>`);
-	let customHighlightShadingXml = "";
-	if (highlight) {
-		if (VALID_HIGHLIGHT_COLORS.has(highlight)) parts.push(`<w:highlight w:val="${highlight}"/>`);
-		else if (!shading) {
-			const hex = highlight.replace(/^#/u, "");
-			if (/^[0-9a-fA-F]{6}$/u.test(hex)) customHighlightShadingXml = `<w:shd w:val="clear" w:color="auto" w:fill="${hex}"/>`;
-		}
-	}
-	if (underline) {
-		const { style, color: underlineColor } = underline;
-		const uAttrs = [`w:val="${style}"`];
-		if (underlineColor) {
-			const { rgb, themeColor, themeTint, themeShade, auto: _auto } = underlineColor;
-			if (rgb && isValidHexColor(rgb)) uAttrs.push(`w:color="${escapeXmlAttribute(rgb)}"`);
-			if (themeColor) uAttrs.push(`w:themeColor="${escapeXmlAttribute(themeColor)}"`);
-			if (themeTint) uAttrs.push(`w:themeTint="${escapeXmlAttribute(themeTint)}"`);
-			if (themeShade) uAttrs.push(`w:themeShade="${escapeXmlAttribute(themeShade)}"`);
-		}
-		parts.push(`<w:u ${uAttrs.join(" ")}/>`);
-	}
-	if (effect) parts.push(`<w:effect w:val="${effect}"/>`);
-	const shadingXml = serializeShading(shading) || customHighlightShadingXml;
-	if (shadingXml) parts.push(shadingXml);
-	if (vertAlign) parts.push(`<w:vertAlign w:val="${vertAlign}"/>`);
-	if (rtl === true) parts.push("<w:rtl/>");
-	else if (rtl === false) parts.push("<w:rtl w:val=\"0\"/>");
-	if (cs === true) parts.push("<w:cs/>");
-	else if (cs === false) parts.push("<w:cs w:val=\"0\"/>");
-	if (emphasisMark) parts.push(`<w:em w:val="${emphasisMark}"/>`);
-	if (language) {
-		const { val, eastAsia, bidi } = language;
-		const languageAttrs = [];
-		if (val) languageAttrs.push(`w:val="${escapeXmlAttribute(val)}"`);
-		if (eastAsia) languageAttrs.push(`w:eastAsia="${escapeXmlAttribute(eastAsia)}"`);
-		if (bidi) languageAttrs.push(`w:bidi="${escapeXmlAttribute(bidi)}"`);
-		if (languageAttrs.length > 0) parts.push(`<w:lang ${languageAttrs.join(" ")}/>`);
-	}
-	return parts.length === 0 ? "" : `<w:rPr>${parts.join("")}</w:rPr>`;
+function serializeTextFormatting(input, owned = []) {
+	const { bold, boldCs, italic, italicCs, underline, strike, doubleStrike, vertAlign, smallCaps, allCaps, hidden, noProof, color, highlight, shading, fontSize, fontSizeCs, fontFamily, language, spacing, position, scale, kerning, effect, emphasisMark, emboss, imprint, outline, shadow, rtl, cs, styleId, preserved } = input ?? {};
+	const namedHighlight = highlight && VALID_HIGHLIGHT_COLORS.has(highlight) ? highlight : void 0;
+	const customHighlightHex = highlight && !namedHighlight && !shading ? highlight.replace(/^#/u, "") : "";
+	const customHighlightShadingXml = /^[0-9a-fA-F]{6}$/u.test(customHighlightHex) ? `<w:shd w:val="clear" w:color="auto" w:fill="${customHighlightHex}"/>` : "";
+	const parts = serializeSequenceChildren({
+		container: "run-properties",
+		modelled: [
+			...owned,
+			["rStyle", styleId ? `<w:rStyle w:val="${escapeXmlAttribute(styleId)}"/>` : ""],
+			["rFonts", serializeFontFamily(fontFamily)],
+			["b", serializeOnOffElement(bold, "b")],
+			["bCs", serializeOnOffElement(boldCs, "bCs")],
+			["i", serializeOnOffElement(italic, "i")],
+			["iCs", serializeOnOffElement(italicCs, "iCs")],
+			["caps", serializeOnOffElement(allCaps, "caps")],
+			["smallCaps", serializeOnOffElement(smallCaps, "smallCaps")],
+			["strike", serializeOnOffElement(strike, "strike")],
+			["dstrike", serializeOnOffElement(doubleStrike, "dstrike")],
+			["outline", serializeOnOffElement(outline, "outline")],
+			["shadow", serializeOnOffElement(shadow, "shadow")],
+			["emboss", serializeOnOffElement(emboss, "emboss")],
+			["imprint", serializeOnOffElement(imprint, "imprint")],
+			["noProof", serializeOnOffElement(noProof, "noProof")],
+			["vanish", serializeOnOffElement(hidden, "vanish")],
+			["color", serializeColorElement(color)],
+			["spacing", numberTag("spacing", spacing)],
+			["w", numberTag("w", roundHorizontalScalePercentForSerialization(scale))],
+			["kern", numberTag("kern", kerning)],
+			["position", numberTag("position", position)],
+			["sz", numberTag("sz", fontSize)],
+			["szCs", numberTag("szCs", fontSizeCs)],
+			["highlight", namedHighlight ? `<w:highlight w:val="${namedHighlight}"/>` : ""],
+			["u", serializeUnderline(underline)],
+			["effect", effect ? `<w:effect w:val="${effect}"/>` : ""],
+			["shd", serializeShading(shading) || customHighlightShadingXml],
+			["vertAlign", vertAlign ? `<w:vertAlign w:val="${vertAlign}"/>` : ""],
+			["rtl", serializeOnOffElement(rtl, "rtl")],
+			["cs", serializeOnOffElement(cs, "cs")],
+			["em", emphasisMark ? `<w:em w:val="${emphasisMark}"/>` : ""],
+			["lang", serializeLanguage(language)]
+		],
+		preserved
+	});
+	if (parts.length === 0) return input !== void 0 && Object.keys(input).length === 0 ? "<w:rPr/>" : "";
+	return `<w:rPr>${parts.join("")}</w:rPr>`;
 }
 //#endregion
 export { serializeShading, serializeTextFormatting };

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

@@ -18,7 +18,7 @@ declare function intAttr(value: number | undefined | null): string;
 /**
  * Verify that `xml` parses to exactly one root element named `expectedLocalName`
  * (namespace prefix ignored). Used to gate raw XML snapshots — e.g. an SDT's
- * `rawPropertiesXml`/`rawEndPropertiesXml` — before splicing them verbatim
+ * `rawEndPropertiesXml` — before splicing it verbatim
  * into a serialized document. Those snapshots are normally produced by our
  * own parser, but they can also arrive from an untrusted surface (a
  * programmatically constructed node, a collaboration payload); a value that

package/dist/docx/serializer/xmlUtils.js

@@ -22,7 +22,7 @@ function intAttr(value) {
 /**
 * Verify that `xml` parses to exactly one root element named `expectedLocalName`
 * (namespace prefix ignored). Used to gate raw XML snapshots — e.g. an SDT's
-* `rawPropertiesXml`/`rawEndPropertiesXml` — before splicing them verbatim
+* `rawEndPropertiesXml` — before splicing it verbatim
 * into a serialized document. Those snapshots are normally produced by our
 * own parser, but they can also arrive from an untrusted surface (a
 * programmatically constructed node, a collaboration payload); a value that

package/dist/docx/server/createBilingualDocument.js

@@ -1,6 +1,6 @@
 import { deterministicHexId } from "../../utils/hexId.js";
 import { createBuiltInStyleIndex, resolveHeadingLevel } from "../builtInStyles.js";
-import { isNumberingReference } from "../numberingReference.js";
+import { mergeParagraphNumbering, paragraphNumberingReference, paragraphNumberingReferenceId } from "../numberingReference.js";
 import { getParagraphText } from "../paragraphParser.js";
 import { cloneParagraphWithoutPropertySource } from "../paragraphPropertySource.js";
 import { getRunText } from "../runParser.js";
@@ -203,6 +203,7 @@ const flattenBlocks = (content) => {
 			out.push(block);
 			return;
 		}
+		if (block.type !== "blockSdt") return;
 		for (const child of block.content) visit(child);
 	};
 	for (const block of content) visit(block);
@@ -246,22 +247,24 @@ const classifyParagraph = (paragraph, styleById, builtInStyles) => {
 	if (effectiveNumPr(paragraph, styleById) !== void 0) return "listItem";
 	return "paragraph";
 };
-/** The numbering a paragraph renders with: direct `numPr`, else the style chain's. */
+/** The numbering a paragraph renders with after style and direct tiers fold. */
 const effectiveNumPr = (paragraph, styleById) => {
-	const direct = paragraph.formatting?.numPr;
-	if (direct?.numId !== void 0) return isNumberingReference(direct.numId) ? direct : void 0;
 	const styleId = paragraph.formatting?.styleId;
-	return styleId ? styleNumPr(styleById.get(styleId), styleById) : void 0;
+	const effective = mergeParagraphNumbering(styleId ? styleNumPr(styleById.get(styleId), styleById) : void 0, paragraph.formatting?.numPr);
+	return effective?.kind === "reference" ? effective : void 0;
 };
 const styleNumPr = (style, styleById) => {
 	const seen = /* @__PURE__ */ new Set();
+	const chain = [];
 	let current = style;
 	while (current && !seen.has(current.styleId)) {
 		seen.add(current.styleId);
-		const numPr = current.pPr?.numPr;
-		if (numPr?.numId !== void 0) return isNumberingReference(numPr.numId) ? numPr : void 0;
+		if (current.pPr?.numPr !== void 0) chain.push(current.pPr.numPr);
 		current = current.basedOn ? styleById.get(current.basedOn) : void 0;
 	}
+	let effective;
+	for (const stated of chain.toReversed()) effective = mergeParagraphNumbering(effective, stated);
+	return effective?.kind === "reference" ? effective : void 0;
 };
 const createNumberingCloner = ({ numbering, styleById, warnings }) => {
 	const abstractNums = numbering?.abstractNums ?? [];
@@ -300,7 +303,7 @@ const createNumberingCloner = ({ numbering, styleById, warnings }) => {
 		let current = abstract;
 		while (current.numStyleLink && !seen.has(current.abstractNumId)) {
 			seen.add(current.abstractNumId);
-			const linkedNumId = styleById.get(current.numStyleLink)?.pPr?.numPr?.numId;
+			const linkedNumId = paragraphNumberingReferenceId(styleById.get(current.numStyleLink)?.pPr?.numPr);
 			const linkedNum = linkedNumId === void 0 ? void 0 : numById.get(linkedNumId);
 			const linkedAbstract = linkedNum ? abstractById.get(linkedNum.abstractNumId) : void 0;
 			if (!linkedAbstract) {
@@ -354,7 +357,7 @@ const createStyleCloner = ({ styleById, suffix, cloner }) => {
 		const style = styleById.get(styleId);
 		if (!style || style.type !== "paragraph") return styleId;
 		const numPr = styleNumPr(style, styleById);
-		if (numPr?.numId === void 0) return styleId;
+		if (numPr === void 0) return styleId;
 		const cloneId = `${styleId}-${suffix}`;
 		if (styleById.has(cloneId)) return cloneId;
 		const clone = {
@@ -365,10 +368,10 @@ const createStyleCloner = ({ styleById, suffix, cloner }) => {
 			default: false,
 			pPr: {
 				...style.pPr,
-				numPr: {
-					...numPr,
-					numId: cloner.cloneNumId(numPr.numId)
-				}
+				numPr: paragraphNumberingReference({
+					numId: cloner.cloneNumId(numPr.numId),
+					ilvl: numPr.ilvl
+				})
 			}
 		};
 		clones.set(styleId, clone);
@@ -388,11 +391,11 @@ const cloneParagraphForTarget = (paragraph, targetParaId, styleCloner, cloner, b
 	const nextFormatting = formatting && {
 		...formatting,
 		...formatting.styleId !== void 0 && { styleId: styleCloner.styleIdFor(formatting.styleId) },
-		...formatting.numPr !== void 0 && isNumberingReference(formatting.numPr.numId) && { numPr: {
+		...formatting.numPr?.kind === "reference" && { numPr: {
 			...formatting.numPr,
 			numId: cloner.cloneNumId(formatting.numPr.numId)
 		} },
-		...formatting.numPrFromStyle !== void 0 && isNumberingReference(formatting.numPrFromStyle.numId) && { numPrFromStyle: {
+		...formatting.numPrFromStyle?.kind === "reference" && { numPrFromStyle: {
 			...formatting.numPrFromStyle,
 			numId: cloner.cloneNumId(formatting.numPrFromStyle.numId)
 		} }
@@ -462,7 +465,7 @@ const remapListRendering = (rendering, cloner) => {
 const collectTableParagraphs = (table) => {
 	const out = [];
 	for (const row of table.rows) for (const cell of row.cells) for (const item of cell.content) if (item.type === "paragraph") out.push(item);
-	else out.push(...collectTableParagraphs(item));
+	else if (item.type === "table") out.push(...collectTableParagraphs(item));
 	return out;
 };
 const cloneTableForTarget = ({ table, editableParagraphIds, paraIds, styleCloner, cloner, bookmarkIds }) => {
@@ -475,6 +478,7 @@ const cloneTableForTarget = ({ table, editableParagraphIds, paraIds, styleCloner
 				...structuredClone(cell),
 				content: cell.content.map((item) => {
 					if (item.type === "table") return cloneTable(item);
+					if (item.type !== "paragraph") return structuredClone(item);
 					const targetParaId = paraIds.mint(item.paraId);
 					const copy = cloneParagraphForTarget(item, targetParaId, styleCloner, cloner, bookmarkIds);
 					if (isTranslatableParagraph(item, editableParagraphIds)) paragraphs.push({

package/dist/docx/server/materializeYjsDocx.d.ts

@@ -4,7 +4,7 @@ declare const FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME = "prosemirror";
 /** Maximum accepted size of a complete Yjs collaboration state update. */
 declare const FOLIO_YJS_UPDATE_MAX_BYTES: number;
 /** Stable failure codes returned by server-side Yjs-to-DOCX materialization. */
-declare const FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES: readonly ["empty_update", "invalid_update", "missing_document", "source_mismatch", "update_too_large"];
+declare const FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES: readonly ["empty_update", "invalid_update", "missing_document", "source_mismatch", "stale_attr_schema", "update_too_large"];
 /** Failure code for a rejected Yjs-to-DOCX materialization request. */
 type FolioYjsDocxMaterializationErrorCode = (typeof FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES)[number];
 declare const FolioYjsDocxMaterializationError_base: import("better-result").TaggedErrorClass<"FolioYjsDocxMaterializationError">;

package/dist/docx/server/materializeYjsDocx.js

@@ -1,6 +1,6 @@
 import { fromProseDoc } from "../../prosemirror/conversion/fromProseDoc.js";
 import { schema } from "../../prosemirror/schema/index.js";
-import { readYjsParagraphSourceContract, withParagraphSourceContract } from "../../prosemirror/yjsParagraphSourceContract.js";
+import { applyAttrSchemaMigrations, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract } from "../../prosemirror/yjsDocumentMetadata.js";
 import { ParagraphPropertySourceValidationError } from "../paragraphPropertySource.js";
 import { parseDocx } from "../parser.js";
 import { repackDocx } from "../rezip.js";
@@ -18,6 +18,7 @@ const FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES = [
 	"invalid_update",
 	"missing_document",
 	"source_mismatch",
+	"stale_attr_schema",
 	"update_too_large"
 ];
 /** Typed failure raised when a collaboration snapshot cannot be materialized. */
@@ -40,6 +41,13 @@ const readProseMirrorDocument = (yjsUpdate) => {
 				code: "missing_document",
 				message: "Yjs update does not contain a Folio document."
 			});
+			const attrSchemaVersion = readYjsAttrSchemaVersion(ydoc);
+			if (attrSchemaVersion.isErr()) throw new FolioYjsDocxMaterializationError({
+				cause: attrSchemaVersion.error,
+				code: "stale_attr_schema",
+				message: attrSchemaVersion.error.message
+			});
+			applyAttrSchemaMigrations(ydoc, fragment, attrSchemaVersion.value);
 			const contract = readYjsParagraphSourceContract(ydoc);
 			if (!contract) throw new FolioYjsDocxMaterializationError({
 				code: "source_mismatch",

package/dist/docx/server/migrateYjsAttrSchema.d.ts

@@ -0,0 +1,55 @@
+import { FolioYjsAttrSchemaVersion } from "../../prosemirror/yjsDocumentMetadata.js";
+import { Result } from "better-result";
+//#region src/docx/server/migrateYjsAttrSchema.d.ts
+/** Stable failure codes returned by an offline snapshot migration. */
+declare const FOLIO_YJS_SNAPSHOT_MIGRATION_ERROR_CODES: readonly ["invalid_update", "unsupported_version", "update_too_large"];
+/** Failure code for a snapshot that could not be migrated. */
+type FolioYjsSnapshotMigrationErrorCode = (typeof FOLIO_YJS_SNAPSHOT_MIGRATION_ERROR_CODES)[number];
+declare const FolioYjsSnapshotMigrationError_base: import("better-result").TaggedErrorClass<"FolioYjsSnapshotMigrationError">;
+/** Typed failure raised when a collaboration snapshot cannot be migrated. */
+declare class FolioYjsSnapshotMigrationError extends FolioYjsSnapshotMigrationError_base<{
+  code: FolioYjsSnapshotMigrationErrorCode;
+  message: string;
+  cause?: unknown;
+}> {}
+/** What an offline migration did to one snapshot. */
+type FolioYjsSnapshotMigrationResult = {
+  /** The complete state update to store in place of the input. */
+  update: Uint8Array;
+  /** The attr-schema version the input was written under. */
+  fromVersion: FolioYjsAttrSchemaVersion;
+  /** The attr-schema version the output carries. */
+  toVersion: FolioYjsAttrSchemaVersion;
+  /** Paragraphs whose attrs the migration rewrote. */
+  paragraphsRewritten: number;
+};
+/**
+ * Carry a stored collaboration snapshot forward to the attr schema this build
+ * writes, without a ProseMirror schema and without rebuilding a single node.
+ *
+ * A Yjs XML element's attributes are ordinary CRDT map entries holding JSON, so
+ * {@link applyAttrSchemaMigrations} rewrites values in the fragment directly.
+ * Nothing here can trip y-prosemirror's node rebuild, which deletes an element
+ * it fails to construct. The function is pure and offline: no network, no
+ * DOCX, no editor.
+ *
+ * A snapshot already at the current version is returned byte for byte, so a
+ * host may run this over its whole corpus repeatedly.
+ *
+ * **The contract a reseed must respect.** This function never reseeds and never
+ * touches the paragraph-source contract: it preserves whichever source binding
+ * the snapshot already carries. A reseed does the opposite, and Folio holds it
+ * to one rule: *the DOCX handed to the seeding editor must be the same bytes
+ * the host will later pass to `materializeYjsDocx` as that room's source*.
+ * The contract is a digest of those bytes, so seeding from one document while
+ * recording another as the room's source makes every later save fail with
+ * `source_mismatch`. The reverse mistake is worse and Folio cannot see it: a
+ * host that reseeds from the document a room was *created* from, rather than
+ * from the latest content it published, produces a perfectly well-formed
+ * snapshot whose collaborative history has been replaced by an older document.
+ * Rebind the recorded source in the same statement that clears the seed, or do
+ * not clear it.
+ */
+declare const migrateFolioYjsSnapshot: (update: Uint8Array) => Result<FolioYjsSnapshotMigrationResult, FolioYjsSnapshotMigrationError>;
+//#endregion
+export { FOLIO_YJS_SNAPSHOT_MIGRATION_ERROR_CODES, FolioYjsSnapshotMigrationError, FolioYjsSnapshotMigrationErrorCode, FolioYjsSnapshotMigrationResult, migrateFolioYjsSnapshot };

package/dist/docx/server/migrateYjsAttrSchema.js

@@ -0,0 +1,95 @@
+import { applyAttrSchemaMigrations, readYjsAttrSchemaVersion } from "../../prosemirror/yjsDocumentMetadata.js";
+import { FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME } from "./materializeYjsDocx.js";
+import { Result, TaggedError } from "better-result";
+import * as Y from "yjs";
+//#region src/docx/server/migrateYjsAttrSchema.ts
+/** Stable failure codes returned by an offline snapshot migration. */
+const FOLIO_YJS_SNAPSHOT_MIGRATION_ERROR_CODES = [
+	"invalid_update",
+	"unsupported_version",
+	"update_too_large"
+];
+/** Typed failure raised when a collaboration snapshot cannot be migrated. */
+var FolioYjsSnapshotMigrationError = class extends TaggedError("FolioYjsSnapshotMigrationError") {};
+/**
+* Carry a stored collaboration snapshot forward to the attr schema this build
+* writes, without a ProseMirror schema and without rebuilding a single node.
+*
+* A Yjs XML element's attributes are ordinary CRDT map entries holding JSON, so
+* {@link applyAttrSchemaMigrations} rewrites values in the fragment directly.
+* Nothing here can trip y-prosemirror's node rebuild, which deletes an element
+* it fails to construct. The function is pure and offline: no network, no
+* DOCX, no editor.
+*
+* A snapshot already at the current version is returned byte for byte, so a
+* host may run this over its whole corpus repeatedly.
+*
+* **The contract a reseed must respect.** This function never reseeds and never
+* touches the paragraph-source contract: it preserves whichever source binding
+* the snapshot already carries. A reseed does the opposite, and Folio holds it
+* to one rule: *the DOCX handed to the seeding editor must be the same bytes
+* the host will later pass to `materializeYjsDocx` as that room's source*.
+* The contract is a digest of those bytes, so seeding from one document while
+* recording another as the room's source makes every later save fail with
+* `source_mismatch`. The reverse mistake is worse and Folio cannot see it: a
+* host that reseeds from the document a room was *created* from, rather than
+* from the latest content it published, produces a perfectly well-formed
+* snapshot whose collaborative history has been replaced by an older document.
+* Rebind the recorded source in the same statement that clears the seed, or do
+* not clear it.
+*/
+const migrateFolioYjsSnapshot = (update) => {
+	if (update.byteLength === 0) return Result.err(new FolioYjsSnapshotMigrationError({
+		code: "invalid_update",
+		message: "Cannot migrate an empty Yjs update."
+	}));
+	if (update.byteLength > 10485760) return Result.err(new FolioYjsSnapshotMigrationError({
+		code: "update_too_large",
+		message: "Yjs update exceeds the snapshot migration limit."
+	}));
+	const ydoc = new Y.Doc();
+	const applied = Result.try({
+		try: () => {
+			Y.applyUpdate(ydoc, update);
+		},
+		catch: (cause) => new FolioYjsSnapshotMigrationError({
+			cause,
+			code: "invalid_update",
+			message: "Yjs update is not a valid Folio collaboration snapshot."
+		})
+	});
+	if (applied.isErr()) {
+		ydoc.destroy();
+		return Result.err(applied.error);
+	}
+	const read = readYjsAttrSchemaVersion(ydoc);
+	if (read.isErr()) {
+		ydoc.destroy();
+		return Result.err(new FolioYjsSnapshotMigrationError({
+			cause: read.error,
+			code: "unsupported_version",
+			message: read.error.message
+		}));
+	}
+	const fromVersion = read.value;
+	if (fromVersion === 11) {
+		ydoc.destroy();
+		return Result.ok({
+			fromVersion,
+			paragraphsRewritten: 0,
+			toVersion: 11,
+			update
+		});
+	}
+	const paragraphsRewritten = applyAttrSchemaMigrations(ydoc, ydoc.getXmlFragment(FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME), fromVersion);
+	const migrated = Y.encodeStateAsUpdate(ydoc);
+	ydoc.destroy();
+	return Result.ok({
+		fromVersion,
+		paragraphsRewritten,
+		toVersion: 11,
+		update: migrated
+	});
+};
+//#endregion
+export { FOLIO_YJS_SNAPSHOT_MIGRATION_ERROR_CODES, FolioYjsSnapshotMigrationError, migrateFolioYjsSnapshot };

package/dist/docx/settingsParser.js

@@ -28,11 +28,14 @@ function parseSettings(xml) {
 	const settings = { defaultTabStop: parseDefaultTabStop(root) };
 	const wordprocessingFlag = (localName) => {
 		const element = findChildByNamespaceUri(root, WORDPROCESSINGML_NAMESPACE_URIS, localName);
-		return element !== null && parseBooleanElement(element);
+		return element === null ? void 0 : parseBooleanElement(element);
 	};
-	if (wordprocessingFlag("evenAndOddHeaders")) settings.evenAndOddHeaders = true;
-	if (wordprocessingFlag("mirrorMargins")) settings.mirrorMargins = true;
-	if (wordprocessingFlag("updateFields")) settings.updateFields = true;
+	const evenAndOddHeaders = wordprocessingFlag("evenAndOddHeaders");
+	if (evenAndOddHeaders !== void 0) settings.evenAndOddHeaders = evenAndOddHeaders;
+	const mirrorMargins = wordprocessingFlag("mirrorMargins");
+	if (mirrorMargins !== void 0) settings.mirrorMargins = mirrorMargins;
+	const updateFields = wordprocessingFlag("updateFields");
+	if (updateFields !== void 0) settings.updateFields = updateFields;
 	const themeFontLangEl = root ? findChild(root, "w", "themeFontLang") : null;
 	const eastAsiaLang = themeFontLangEl ? getAttribute(themeFontLangEl, "w", "eastAsia") || void 0 : void 0;
 	const bidiLang = themeFontLangEl ? getAttribute(themeFontLangEl, "w", "bidi") || void 0 : void 0;

package/dist/docx/shadingParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/shadingParser.d.ts
-declare function parseShading(shd: XmlElement | null): document_d_exports.ShadingProperties | undefined;
+declare function parseShading(shd: XmlElement | null, context?: ParseContext): document_d_exports.ShadingProperties | undefined;
 //#endregion
 export { parseShading };