@stll/folio-core 0.33.0 → 0.33.2

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

@@ -0,0 +1,78 @@
+import { OoxmlPrefix } from "@stll/docx-utils";
+//#region src/docx/serializer/partNamespaces.d.ts
+/**
+ * A namespace a rebuilt WordprocessingML part may declare.
+ *
+ * `ignorable` marks an extension that decorates baseline elements in place
+ * (`w14:paraId`, `w16du:dateUtc`, `wp14:sizeRelH`): a consumer that predates it
+ * has to be told through `mc:Ignorable` to skip it, or it rejects the part.
+ * Extensions reachable only inside an `mc:AlternateContent` choice or an
+ * `a:graphicData` payload (`wps`, `wpg`, `wne`, `cx*`) are already gated by
+ * that wrapper, so they stay out of the attribute, as mainstream producers
+ * leave them.
+ */
+type OoxmlNamespace = {
+  readonly uri: string;
+  readonly ignorable: boolean;
+};
+/** Packaging prefixes; they never appear inside a WordprocessingML part. */
+type PackagingPrefix = "ct" | "pr";
+/**
+ * A prefix folio can bind on a rebuilt part without consulting the source.
+ *
+ * Every prefix the parser resolves is a member, so a prefix the parser
+ * understands can always be written back, and {@link OOXML_NAMESPACES} is total
+ * over the union: a member with no entry, or an entry with no member, does not
+ * compile.
+ */
+type OoxmlNamespacePrefix = Exclude<OoxmlPrefix, PackagingPrefix> | "cx" | "cx1" | "cx2" | "cx3" | "cx4" | "cx5" | "cx6" | "cx7" | "cx8" | "aink" | "am3d" | "oel" | "w10" | "w16" | "w16cex" | "w16cid" | "w16du" | "w16sdtdh" | "w16se" | "wpi" | "wne";
+/**
+ * Every namespace a rebuilt part can declare, in the order producers write them.
+ *
+ * URIs shared with the parser are taken from its table rather than retyped, so
+ * the two cannot drift.
+ */
+declare const OOXML_NAMESPACES: Readonly<Record<OoxmlNamespacePrefix, OoxmlNamespace>>;
+declare const UnboundNamespacePrefixError_base: import("better-result").TaggedErrorClass<"UnboundNamespacePrefixError">;
+/** A rebuilt part uses a prefix that resolves to no namespace URI. */
+declare class UnboundNamespacePrefixError extends UnboundNamespacePrefixError_base<{
+  message: string;
+  partPath: string;
+  prefixes: readonly string[];
+}> {}
+/**
+ * The `xmlns:*` bindings a source part declared on its root element.
+ *
+ * Reused when the part is rebuilt so a producer-specific prefix that
+ * {@link OOXML_NAMESPACES} does not know keeps the URI the document gave it.
+ */
+declare const readRootNamespaceBindings: (partXml: string) => ReadonlyMap<string, string>;
+/** The part a rebuild replaces: where it lives, and what its root element bound. */
+type SourcePart = {
+  path: string;
+  bindings: ReadonlyMap<string, string>;
+};
+type PartElementOptions = {
+  /** Package-relative path of the part, reported when a prefix is unbound. */
+  partPath: string;
+  /** Qualified name of the root element, for example `w:document`. */
+  rootName: string;
+  /** Root-element attributes other than the namespace declarations. */
+  rootAttributes?: string;
+  /**
+   * Prefixes declared whether or not the body uses them, so the part keeps a
+   * stable shape across saves and unmodeled extensions have somewhere to land.
+   */
+  baselinePrefixes: readonly OoxmlNamespacePrefix[];
+  /** Root bindings of the part being replaced, when the save has the source. */
+  sourceBindings: ReadonlyMap<string, string> | undefined;
+  /** Assembled part content, everything between the root tags. */
+  body: string;
+};
+/**
+ * Wrap an assembled part body in a root element that declares every prefix the
+ * part uses and lists the ignorable ones in `mc:Ignorable`.
+ */
+declare const serializePartElement: ({ partPath, rootName, rootAttributes, baselinePrefixes, sourceBindings, body }: PartElementOptions) => string;
+//#endregion
+export { OOXML_NAMESPACES, OoxmlNamespace, OoxmlNamespacePrefix, PartElementOptions, SourcePart, UnboundNamespacePrefixError, readRootNamespaceBindings, serializePartElement };

package/dist/docx/serializer/partNamespaces.js

@@ -0,0 +1,324 @@
+import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
+import { escapeXml } from "./xmlUtils.js";
+import { TaggedError } from "better-result";
+import { OOXML_NS } from "@stll/docx-utils";
+//#region src/docx/serializer/partNamespaces.ts
+/**
+* Namespace declarations for parts folio rebuilds from the model.
+*
+* A rebuilt part carries content the parser preserved verbatim: raw property
+* XML, text-box bodies, drawing extensions, unmodeled attributes. That content
+* can use any prefix its producer bound on the source part's root, so a
+* hand-maintained declaration list on the serializer silently drops bindings
+* and emits an unbound prefix, which makes the part malformed and the package
+* unopenable. The declarations are therefore derived: every prefix the
+* assembled part actually uses is resolved through {@link OOXML_NAMESPACES},
+* falling back to what the source part bound, and a prefix that resolves to
+* nothing fails the save instead of being written unbound.
+*/
+/**
+* Every namespace a rebuilt part can declare, in the order producers write them.
+*
+* URIs shared with the parser are taken from its table rather than retyped, so
+* the two cannot drift.
+*/
+const OOXML_NAMESPACES = {
+	wpc: {
+		uri: OOXML_NS.wpc,
+		ignorable: false
+	},
+	cx: {
+		uri: "http://schemas.microsoft.com/office/drawing/2014/chartex",
+		ignorable: false
+	},
+	cx1: {
+		uri: "http://schemas.microsoft.com/office/drawing/2015/9/8/chartex",
+		ignorable: false
+	},
+	cx2: {
+		uri: "http://schemas.microsoft.com/office/drawing/2015/10/21/chartex",
+		ignorable: false
+	},
+	cx3: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/9/chartex",
+		ignorable: false
+	},
+	cx4: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/10/chartex",
+		ignorable: false
+	},
+	cx5: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/11/chartex",
+		ignorable: false
+	},
+	cx6: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/12/chartex",
+		ignorable: false
+	},
+	cx7: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/13/chartex",
+		ignorable: false
+	},
+	cx8: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/5/14/chartex",
+		ignorable: false
+	},
+	mc: {
+		uri: OOXML_NS.mc,
+		ignorable: false
+	},
+	aink: {
+		uri: "http://schemas.microsoft.com/office/drawing/2016/ink",
+		ignorable: false
+	},
+	am3d: {
+		uri: "http://schemas.microsoft.com/office/drawing/2017/model3d",
+		ignorable: false
+	},
+	o: {
+		uri: OOXML_NS.o,
+		ignorable: false
+	},
+	oel: {
+		uri: "http://schemas.microsoft.com/office/2019/extlst",
+		ignorable: false
+	},
+	r: {
+		uri: OOXML_NS.r,
+		ignorable: false
+	},
+	m: {
+		uri: OOXML_NS.m,
+		ignorable: false
+	},
+	v: {
+		uri: OOXML_NS.v,
+		ignorable: false
+	},
+	wp14: {
+		uri: OOXML_NS.wp14,
+		ignorable: true
+	},
+	wp: {
+		uri: OOXML_NS.wp,
+		ignorable: false
+	},
+	w10: {
+		uri: "urn:schemas-microsoft-com:office:word",
+		ignorable: false
+	},
+	w: {
+		uri: OOXML_NS.w,
+		ignorable: false
+	},
+	w14: {
+		uri: OOXML_NS.w14,
+		ignorable: true
+	},
+	w15: {
+		uri: OOXML_NS.w15,
+		ignorable: true
+	},
+	w16cex: {
+		uri: "http://schemas.microsoft.com/office/word/2018/wordml/cex",
+		ignorable: true
+	},
+	w16cid: {
+		uri: "http://schemas.microsoft.com/office/word/2016/wordml/cid",
+		ignorable: true
+	},
+	w16: {
+		uri: "http://schemas.microsoft.com/office/word/2018/wordml",
+		ignorable: true
+	},
+	w16du: {
+		uri: "http://schemas.microsoft.com/office/word/2023/wordml/word16du",
+		ignorable: true
+	},
+	w16sdtdh: {
+		uri: "http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash",
+		ignorable: true
+	},
+	w16se: {
+		uri: "http://schemas.microsoft.com/office/word/2015/wordml/symex",
+		ignorable: true
+	},
+	wpg: {
+		uri: OOXML_NS.wpg,
+		ignorable: false
+	},
+	wpi: {
+		uri: "http://schemas.microsoft.com/office/word/2010/wordprocessingInk",
+		ignorable: false
+	},
+	wne: {
+		uri: "http://schemas.microsoft.com/office/word/2006/wordml",
+		ignorable: false
+	},
+	wps: {
+		uri: OOXML_NS.wps,
+		ignorable: false
+	},
+	a: {
+		uri: OOXML_NS.a,
+		ignorable: false
+	},
+	pic: {
+		uri: OOXML_NS.pic,
+		ignorable: false
+	}
+};
+/** {@link OOXML_NAMESPACES} keyed for lookup by a prefix read out of markup. */
+const NAMESPACE_TABLE = new Map(Object.entries(OOXML_NAMESPACES));
+/** A rebuilt part uses a prefix that resolves to no namespace URI. */
+var UnboundNamespacePrefixError = class extends TaggedError("UnboundNamespacePrefixError") {};
+const XMLNS_ATTRIBUTE_PREFIX = "xmlns:";
+/** Bound by the XML specification itself; never declared. */
+const RESERVED_PREFIX = "xml";
+const isWhitespace = (character) => character === " " || character === "	" || character === "\n" || character === "\r";
+const isNameBoundary = (character) => isWhitespace(character) || character === ">" || character === "/" || character === "=";
+const namePrefix = (qualifiedName) => {
+	const colon = qualifiedName.indexOf(":");
+	if (colon <= 0) return;
+	const prefix = qualifiedName.slice(0, colon);
+	return prefix === RESERVED_PREFIX ? void 0 : prefix;
+};
+/**
+* Collect prefixes from element and attribute names in one quote-aware pass.
+*
+* Attribute values are skipped rather than matched, so a URI or a text value
+* containing a colon cannot be mistaken for a namespace prefix.
+*/
+const scanXmlNames = (xml, rootTagOnly) => {
+	const used = /* @__PURE__ */ new Set();
+	const declared = /* @__PURE__ */ new Map();
+	const length = xml.length;
+	let index = 0;
+	while (index < length) {
+		const tagStart = xml.indexOf("<", index);
+		if (tagStart === -1) break;
+		index = tagStart + 1;
+		if (xml.startsWith("?", index)) {
+			const end = xml.indexOf("?>", index);
+			if (end === -1) break;
+			index = end + 2;
+			continue;
+		}
+		if (xml.startsWith("!--", index)) {
+			const end = xml.indexOf("-->", index);
+			if (end === -1) break;
+			index = end + 3;
+			continue;
+		}
+		if (xml.startsWith("![CDATA[", index)) {
+			const end = xml.indexOf("]]>", index);
+			if (end === -1) break;
+			index = end + 3;
+			continue;
+		}
+		if (xml.startsWith("!", index)) {
+			const end = xml.indexOf(">", index);
+			if (end === -1) break;
+			index = end + 1;
+			continue;
+		}
+		if (xml.startsWith("/", index)) index += 1;
+		const nameStart = index;
+		while (index < length && !isNameBoundary(xml[index] ?? ">")) index += 1;
+		const elementPrefix = namePrefix(xml.slice(nameStart, index));
+		if (elementPrefix) used.add(elementPrefix);
+		while (index < length) {
+			const character = xml[index] ?? ">";
+			if (isWhitespace(character) || character === "/") {
+				index += 1;
+				continue;
+			}
+			if (character === ">") {
+				index += 1;
+				break;
+			}
+			const attributeStart = index;
+			while (index < length && !isNameBoundary(xml[index] ?? ">")) index += 1;
+			const attributeName = xml.slice(attributeStart, index);
+			while (index < length && isWhitespace(xml[index] ?? ">")) index += 1;
+			let value = "";
+			if (xml[index] === "=") {
+				index += 1;
+				while (index < length && isWhitespace(xml[index] ?? ">")) index += 1;
+				const quote = xml[index];
+				if (quote === "\"" || quote === "'") {
+					const valueEnd = xml.indexOf(quote, index + 1);
+					if (valueEnd === -1) {
+						index = length;
+						break;
+					}
+					value = xml.slice(index + 1, valueEnd);
+					index = valueEnd + 1;
+				}
+			}
+			if (attributeName.startsWith(XMLNS_ATTRIBUTE_PREFIX)) {
+				declared.set(attributeName.slice(6), value);
+				continue;
+			}
+			const attributePrefix = namePrefix(attributeName);
+			if (attributePrefix) used.add(attributePrefix);
+		}
+		if (rootTagOnly) break;
+	}
+	return {
+		used,
+		declared
+	};
+};
+/**
+* The `xmlns:*` bindings a source part declared on its root element.
+*
+* Reused when the part is rebuilt so a producer-specific prefix that
+* {@link OOXML_NAMESPACES} does not know keeps the URI the document gave it.
+*/
+const readRootNamespaceBindings = (partXml) => scanXmlNames(partXml, true).declared;
+/**
+* Wrap an assembled part body in a root element that declares every prefix the
+* part uses and lists the ignorable ones in `mc:Ignorable`.
+*/
+const serializePartElement = ({ partPath, rootName, rootAttributes, baselinePrefixes, sourceBindings, body }) => {
+	const openingTag = `<${rootName}${rootAttributes ? ` ${rootAttributes}` : ""}`;
+	const fromRoot = scanXmlNames(`${openingTag}/>`, true);
+	const { used, declared } = scanXmlNames(body, false);
+	const required = /* @__PURE__ */ new Set([...fromRoot.used, ...used]);
+	const bindings = /* @__PURE__ */ new Map();
+	for (const prefix of baselinePrefixes) bindings.set(prefix, OOXML_NAMESPACES[prefix].uri);
+	const unbound = [];
+	for (const prefix of required) {
+		if (bindings.has(prefix)) continue;
+		const sourceBinding = sourceBindings?.get(prefix);
+		const uri = NAMESPACE_TABLE.get(prefix)?.uri ?? (sourceBinding === void 0 ? void 0 : toTransitionalNamespaceUri(sourceBinding));
+		if (uri !== void 0) {
+			bindings.set(prefix, uri);
+			continue;
+		}
+		if (!declared.has(prefix)) unbound.push(prefix);
+	}
+	if (unbound.length > 0) {
+		const prefixes = unbound.sort();
+		throw new UnboundNamespacePrefixError({
+			message: `${partPath} uses namespace prefixes bound to no URI: ${prefixes.join(", ")}`,
+			partPath,
+			prefixes
+		});
+	}
+	if ([...bindings.keys()].some((prefix) => NAMESPACE_TABLE.get(prefix)?.ignorable === true)) bindings.set("mc", OOXML_NAMESPACES.mc.uri);
+	const baseline = new Set(baselinePrefixes);
+	const extra = new Set([...bindings.keys()].filter((prefix) => !baseline.has(prefix)));
+	const orderedPrefixes = [
+		...baselinePrefixes,
+		...[...NAMESPACE_TABLE.keys()].filter((prefix) => extra.has(prefix)),
+		...[...extra].filter((prefix) => !NAMESPACE_TABLE.has(prefix)).sort()
+	];
+	const attributes = orderedPrefixes.map((prefix) => `xmlns:${prefix}="${escapeXml(bindings.get(prefix))}"`);
+	const ignorable = orderedPrefixes.filter((prefix) => NAMESPACE_TABLE.get(prefix)?.ignorable === true);
+	if (ignorable.length > 0) attributes.push(`mc:Ignorable="${ignorable.join(" ")}"`);
+	return `${openingTag} ${attributes.join(" ")}>${body}</${rootName}>`;
+};
+//#endregion
+export { OOXML_NAMESPACES, UnboundNamespacePrefixError, readRootNamespaceBindings, serializePartElement };

package/dist/docx/serializer/runSerializer.js

@@ -525,7 +525,7 @@ function serializeShapeContent(content) {
 			"<wps:wsp>",
 			`<wps:cNvSpPr${isTextBox ? " txBox=\"1\"" : ""}/>`,
 			spPr,
-			textBody,
+			textBody === "" ? "<wps:bodyPr/>" : textBody,
 			"</wps:wsp>"
 		].join(""),
 		"</a:graphicData>",

package/dist/docx/serializer/settingsSerializer.js

@@ -1,6 +1,6 @@
+import { serializePartElement } from "./partNamespaces.js";
 import { escapeXml, intAttr } from "./xmlUtils.js";
 //#region src/docx/serializer/settingsSerializer.ts
-const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
 const serializeSettingsXml = (settings) => {
 	const parts = [`<w:defaultTabStop w:val="${intAttr(settings.defaultTabStop)}"/>`];
 	if (settings.evenAndOddHeaders) parts.push("<w:evenAndOddHeaders/>");
@@ -11,7 +11,13 @@ const serializeSettingsXml = (settings) => {
 		if (settings.themeFontLang.bidi) attrs.push(`w:bidi="${escapeXml(settings.themeFontLang.bidi)}"`);
 		if (attrs.length > 0) parts.push(`<w:themeFontLang ${attrs.join(" ")}/>`);
 	}
-	return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:settings xmlns:w="${W_NS}">${parts.join("")}</w:settings>`;
+	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
+		partPath: "word/settings.xml",
+		rootName: "w:settings",
+		baselinePrefixes: ["w"],
+		sourceBindings: void 0,
+		body: parts.join("")
+	});
 };
 //#endregion
 export { serializeSettingsXml };

package/dist/docx/serializer/stylesSerializer.js

@@ -1,14 +1,17 @@
 import { serializeParagraphFormatting } from "./paragraphSerializer.js";
+import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./runSerializer.js";
 import { serializeTableCellFormatting, serializeTableFormatting, serializeTableRowFormatting } from "./tableSerializer.js";
 import { escapeXml } from "./xmlUtils.js";
 //#region src/docx/serializer/stylesSerializer.ts
-const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
 const serializeStylesXml = (definitions) => {
-	const docDefaults = serializeDocumentDefaults(definitions);
-	const latentStyles = serializeLatentStyles(definitions);
-	const styles = definitions.styles.map(serializeStyle).join("");
-	return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:styles xmlns:w="${W_NS}">${docDefaults}${latentStyles}${styles}</w:styles>`;
+	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
+		partPath: "word/styles.xml",
+		rootName: "w:styles",
+		baselinePrefixes: ["w"],
+		sourceBindings: void 0,
+		body: `${serializeDocumentDefaults(definitions)}${serializeLatentStyles(definitions)}${definitions.styles.map(serializeStyle).join("")}`
+	});
 };
 const serializeDocumentDefaults = (definitions) => {
 	return `<w:docDefaults><w:rPrDefault>${serializeTextFormatting(definitions.docDefaults?.rPr) || "<w:rPr/>"}</w:rPrDefault><w:pPrDefault>${serializeParagraphFormatting(definitions.docDefaults?.pPr) || "<w:pPr/>"}</w:pPrDefault></w:docDefaults>`;

package/dist/docx/serializer/tableSerializer.js

@@ -1,8 +1,74 @@
+import { canonicalJson } from "../../utils/canonicalJson.js";
 import { isValidHexColor } from "../../utils/colorResolver.js";
+import { parseTableCellProperties, parseTableGrid, parseTableProperties, parseTableRowProperties } from "../tableParser.js";
+import { OOXML_NAMESPACE_SCOPE, parseXml } from "../xmlParser.js";
 import { serializeBorder } from "./borderSerializer.js";
 import { escapeXml, intAttr } from "./xmlUtils.js";
 import { normalizeRevisionId } from "@stll/docx-core/model";
 //#region src/docx/serializer/tableSerializer.ts
+/**
+* The captured element with the revision children written back into it.
+*
+* The capture holds properties only, so a revision the model carries — a row
+* marked inserted, a `w:tcPrChange` — is appended here rather than forcing the
+* whole element to be rebuilt and losing everything the model does not cover.
+*/
+const withRevisionChildren = (sourceXml, revisions) => {
+	const written = revisions.join("");
+	if (written.length === 0) return sourceXml;
+	if (sourceXml.endsWith("/>")) {
+		const name = sourceXml.slice(1, sourceXml.length - 2).split(/[\s/]/u)[0] ?? "";
+		return `${sourceXml.slice(0, -2)}>${written}</${name}>`;
+	}
+	const close = sourceXml.lastIndexOf("</");
+	return close === -1 ? sourceXml : `${sourceXml.slice(0, close)}${written}${sourceXml.slice(close)}`;
+};
+/** `w:trPr/w:ins` | `w:trPr/w:del`, the row's own structural revision. */
+const rowStructuralChangeXml = (change) => {
+	if (change?.type === "tableRowInsertion") return [`<w:ins ${serializeTrackedChangeAttributes(change.info)}/>`];
+	if (change?.type === "tableRowDeletion") return [`<w:del ${serializeTrackedChangeAttributes(change.info)}/>`];
+	return [];
+};
+/** `w:tcPr/w:cellIns` | `w:cellDel` | `w:cellMerge`, the cell's own. */
+const cellStructuralChangeXml = (change) => {
+	if (change?.type === "tableCellInsertion") return [`<w:cellIns ${serializeTrackedChangeAttributes(change.info)}/>`];
+	if (change?.type === "tableCellDeletion") return [`<w:cellDel ${serializeTrackedChangeAttributes(change.info)}/>`];
+	if (change?.type !== "tableCellMerge") return [];
+	const attrs = [serializeTrackedChangeAttributes(change.info)];
+	if (change.verticalMerge) attrs.push(`w:vMerge="${change.verticalMerge === "continue" ? "cont" : "rest"}"`);
+	if (change.verticalMergeOriginal) attrs.push(`w:vMergeOrig="${change.verticalMergeOriginal === "continue" ? "cont" : "rest"}"`);
+	return [`<w:cellMerge ${attrs.join(" ")}/>`];
+};
+/**
+* A property set without the elements kept beside it. Only the typed values
+* decide whether a capture still describes the node; the captures themselves
+* are what is being decided about.
+*/
+const withoutCaptures = (formatting) => {
+	const { sourceXml: _source, gridSourceXml: _grid, ...rest } = formatting ?? {};
+	return rest;
+};
+/**
+* The element a formatting object was parsed from, when it still describes it.
+*
+* `sourceXml` is only usable while the typed values around it are the ones it
+* was parsed into. Anything may edit a `Document` in place — a host building
+* one by hand, a migration, a test — and a capture written back over a changed
+* model would silently discard the change. So the capture is re-parsed and
+* checked rather than trusted: it is written only when parsing it reproduces
+* the formatting it sits on.
+*
+* The re-parse runs under {@link OOXML_NAMESPACE_SCOPE} because a captured
+* fragment carries no `xmlns` of its own. A document that binds the
+* WordprocessingML prefix differently fails the check and is rebuilt from the
+* model, which is what happened to every document before the capture existed.
+*/
+const verifiedSourceXml = (formatting, parse) => {
+	if (formatting === void 0 || formatting.sourceXml === void 0) return null;
+	const { sourceXml } = formatting;
+	const reparsed = parse(parseXml(sourceXml, OOXML_NAMESPACE_SCOPE).elements?.[0] ?? null);
+	return canonicalJson(withoutCaptures(reparsed)) === canonicalJson(withoutCaptures(formatting)) ? sourceXml : null;
+};
 function normalizeTrackedChangeInfo(info) {
 	const normalizedId = normalizeRevisionId(info.id);
 	const authorCandidate = typeof info.author === "string" ? info.author.trim() : "";
@@ -18,6 +84,7 @@ function serializeTrackedChangeAttributes(info, rsid) {
 	const normalized = normalizeTrackedChangeInfo(info);
 	const attrs = [`w:id="${normalized.id}"`, `w:author="${escapeXml(normalized.author)}"`];
 	if (normalized.date) attrs.push(`w:date="${escapeXml(normalized.date)}"`);
+	if (info.utcDate) attrs.push(`${info.utcDate.attribute}="${escapeXml(info.utcDate.value)}"`);
 	if (rsid && rsid.trim().length > 0) attrs.push(`w:rsid="${escapeXml(rsid.trim())}"`);
 	return attrs.join(" ");
 }
@@ -129,11 +196,14 @@ function serializeFloatingTableProperties(floating) {
 * Serialize table formatting properties (w:tblPr)
 */
 function serializeTableFormatting(formatting, propertyChanges) {
+	const tableSource = verifiedSourceXml(formatting, parseTableProperties);
+	if (tableSource !== null) return withRevisionChildren(tableSource, (propertyChanges ?? []).map((change) => serializeTablePropertyChange(change)));
 	const parts = [];
 	if (formatting) {
 		if (formatting.styleId) parts.push(`<w:tblStyle w:val="${escapeXml(formatting.styleId)}"/>`);
 		const floatingXml = serializeFloatingTableProperties(formatting.floating);
 		if (floatingXml) parts.push(floatingXml);
+		if (formatting.overlap) parts.push(`<w:tblOverlap w:val="${formatting.overlap}"/>`);
 		if (formatting.bidi !== void 0) parts.push(formatting.bidi ? "<w:bidiVisual/>" : "<w:bidiVisual w:val=\"0\"/>");
 		const widthXml = serializeMeasurement(formatting.width, "tblW");
 		if (widthXml) parts.push(widthXml);
@@ -144,14 +214,13 @@ function serializeTableFormatting(formatting, propertyChanges) {
 		if (indentXml) parts.push(indentXml);
 		const bordersXml = serializeTableBorders(formatting.borders, "tblBorders");
 		if (bordersXml) parts.push(bordersXml);
-		const marginsXml = serializeCellMargins(formatting.cellMargins, "tblCellMar");
-		if (marginsXml) parts.push(marginsXml);
-		if (formatting.layout) parts.push(`<w:tblLayout w:type="${formatting.layout}"/>`);
 		const shadingXml = serializeShading(formatting.shading);
 		if (shadingXml) parts.push(shadingXml);
+		if (formatting.layout) parts.push(`<w:tblLayout w:type="${formatting.layout}"/>`);
+		const marginsXml = serializeCellMargins(formatting.cellMargins, "tblCellMar");
+		if (marginsXml) parts.push(marginsXml);
 		const lookXml = serializeTableLook(formatting.look);
 		if (lookXml) parts.push(lookXml);
-		if (formatting.overlap) parts.push(`<w:tblOverlap w:val="${formatting.overlap}"/>`);
 	}
 	if (propertyChanges && propertyChanges.length > 0) parts.push(...propertyChanges.map((change) => serializeTablePropertyChange(change)));
 	if (parts.length === 0) return "";
@@ -170,6 +239,8 @@ function serializeTablePropertyChange(change) {
 * Serialize table row formatting properties (w:trPr)
 */
 function serializeTableRowFormatting(formatting, propertyChanges, structuralChange) {
+	const rowSource = verifiedSourceXml(formatting, parseTableRowProperties);
+	if (rowSource !== null) return withRevisionChildren(rowSource, [...rowStructuralChangeXml(structuralChange), ...(propertyChanges ?? []).map((change) => serializeTableRowPropertyChange(change))]);
 	const parts = [];
 	if (formatting) {
 		const cnfStyleXml = serializeConditionalFormatStyle(formatting.conditionalFormat);
@@ -188,10 +259,7 @@ function serializeTableRowFormatting(formatting, propertyChanges, structuralChan
 		if (formatting.justification) parts.push(`<w:jc w:val="${formatting.justification}"/>`);
 		if (formatting.hidden) parts.push("<w:hidden/>");
 	}
-	if (structuralChange) {
-		if (structuralChange.type === "tableRowInsertion") parts.push(`<w:ins ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
-		else if (structuralChange.type === "tableRowDeletion") parts.push(`<w:del ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
-	}
+	parts.push(...rowStructuralChangeXml(structuralChange));
 	if (propertyChanges && propertyChanges.length > 0) parts.push(...propertyChanges.map((change) => serializeTableRowPropertyChange(change)));
 	if (parts.length === 0) return "";
 	return `<w:trPr>${parts.join("")}</w:trPr>`;
@@ -231,6 +299,8 @@ function serializeConditionalFormatStyle(style) {
 * Serialize table cell formatting properties (w:tcPr)
 */
 function serializeTableCellFormatting(formatting, propertyChanges, structuralChange) {
+	const cellSource = verifiedSourceXml(formatting, parseTableCellProperties);
+	if (cellSource !== null) return withRevisionChildren(cellSource, [...cellStructuralChangeXml(structuralChange), ...(propertyChanges ?? []).map((change) => serializeTableCellPropertyChange(change))]);
 	const parts = [];
 	if (formatting) {
 		const cnfStyleXml = serializeConditionalFormatStyle(formatting.conditionalFormat);
@@ -253,16 +323,7 @@ function serializeTableCellFormatting(formatting, propertyChanges, structuralCha
 		if (formatting.hideMark === true) parts.push("<w:hideMark/>");
 		else if (formatting.hideMark === false) parts.push("<w:hideMark w:val=\"off\"/>");
 	}
-	if (structuralChange) {
-		if (structuralChange.type === "tableCellInsertion") parts.push(`<w:cellIns ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
-		else if (structuralChange.type === "tableCellDeletion") parts.push(`<w:cellDel ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
-		else if (structuralChange.type === "tableCellMerge") {
-			const attrs = [serializeTrackedChangeAttributes(structuralChange.info)];
-			if (structuralChange.verticalMerge) attrs.push(`w:vMerge="${structuralChange.verticalMerge === "continue" ? "cont" : "rest"}"`);
-			if (structuralChange.verticalMergeOriginal) attrs.push(`w:vMergeOrig="${structuralChange.verticalMergeOriginal === "continue" ? "cont" : "rest"}"`);
-			parts.push(`<w:cellMerge ${attrs.join(" ")}/>`);
-		}
-	}
+	parts.push(...cellStructuralChangeXml(structuralChange));
 	if (propertyChanges && propertyChanges.length > 0) parts.push(...propertyChanges.map((change) => serializeTableCellPropertyChange(change)));
 	if (parts.length === 0) return "";
 	return `<w:tcPr>${parts.join("")}</w:tcPr>`;
@@ -277,11 +338,34 @@ function serializeTableCellPropertyChange(change) {
 	return `<w:tcPrChange ${attrs}>${previousTcPrInner.length > 0 ? `<w:tcPr>${previousTcPrInner}</w:tcPr>` : "<w:tcPr/>"}</w:tcPrChange>`;
 }
 /**
-* Serialize table grid (w:tblGrid)
+* Columns the grid has to declare: the widest row's span total, because a grid
+* narrower than a row leaves cells with no column to sit in.
 */
-function serializeTableGrid(columnWidths) {
-	if (!columnWidths || columnWidths.length === 0) return "";
-	return `<w:tblGrid>${columnWidths.map((w) => `<w:gridCol w:w="${intAttr(w)}"/>`).join("")}</w:tblGrid>`;
+function gridColumnCount(table) {
+	let widest = 0;
+	for (const row of table.rows) {
+		let columns = 0;
+		for (const cell of row.cells) columns += cell.formatting?.gridSpan ?? 1;
+		widest = Math.max(widest, columns);
+	}
+	return widest;
+}
+/**
+* Serialize table grid (w:tblGrid).
+*
+* `w:tblGrid` is required on every `w:tbl` and `w:w` is optional on a
+* `w:gridCol`, so a table whose column widths were never measured — one the
+* comparison creates, say — still declares a grid, just without widths.
+*/
+function serializeTableGrid(table) {
+	const columnWidths = table.columnWidths;
+	const gridSourceXml = table.formatting?.gridSourceXml;
+	if (gridSourceXml !== void 0) {
+		if (canonicalJson(parseTableGrid(parseXml(gridSourceXml, OOXML_NAMESPACE_SCOPE).elements?.[0] ?? null)) === canonicalJson(columnWidths)) return gridSourceXml;
+	}
+	if (columnWidths && columnWidths.length > 0) return `<w:tblGrid>${columnWidths.map((w) => `<w:gridCol w:w="${intAttr(w)}"/>`).join("")}</w:tblGrid>`;
+	const columns = gridColumnCount(table);
+	return columns === 0 ? "<w:tblGrid/>" : `<w:tblGrid>${"<w:gridCol/>".repeat(columns)}</w:tblGrid>`;
 }
 /**
 * Serialize cell content (paragraphs, nested tables)
@@ -320,11 +404,7 @@ function serializeTableRow(row, serializeParagraph) {
 * @returns XML string for the table
 */
 function serializeTable(table, serializeParagraph) {
-	const parts = [];
-	const tblPrXml = serializeTableFormatting(table.formatting, table.propertyChanges);
-	if (tblPrXml) parts.push(tblPrXml);
-	const tblGridXml = serializeTableGrid(table.columnWidths);
-	if (tblGridXml) parts.push(tblGridXml);
+	const parts = [serializeTableFormatting(table.formatting, table.propertyChanges) || "<w:tblPr/>", serializeTableGrid(table)];
 	for (const row of table.rows) parts.push(serializeTableRow(row, serializeParagraph));
 	return `<w:tbl>${parts.join("")}</w:tbl>`;
 }