@stll/folio-core 0.43.0 → 0.45.0

package/dist/docx/serializer/commentSerializer.js

@@ -1,8 +1,9 @@
 import { deterministicHexId } from "../../utils/hexId.js";
+import { commentThreadParaId } from "../commentThreadKey.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/commentSerializer.ts
 /**
 * Comment Serializer
@@ -26,9 +27,9 @@ function serializeParagraphWithAnnotationRef(paragraph, formatting) {
 	return xml.replace(/^<w:p(?=[\s>])[^>]*>/u, (openingTag) => `${openingTag}${annotationReference}`);
 }
 function serializeComment(comment) {
-	const attrs = [`w:id="${comment.id}"`, `w:author="${escapeXml(comment.author)}"`];
-	if (comment.initials !== void 0) attrs.push(`w:initials="${escapeXml(comment.initials)}"`);
-	if (comment.date) attrs.push(`w:date="${escapeXml(comment.date)}"`);
+	const attrs = [`w:id="${comment.id}"`, `w:author="${escapeXmlAttribute(comment.author)}"`];
+	if (comment.initials !== void 0) attrs.push(`w:initials="${escapeXmlAttribute(comment.initials)}"`);
+	if (comment.date) attrs.push(`w:date="${escapeXmlAttribute(comment.date)}"`);
 	let xml = `<w:comment ${attrs.join(" ")}>`;
 	if (comment.content.length > 0) {
 		xml += serializeParagraphWithAnnotationRef(comment.content[0], comment.annotationReferenceFormatting);
@@ -61,33 +62,6 @@ const COMMENTS_EXTENDED_BASELINE_PREFIXES = [
 ];
 const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
 /**
-* Serialize comments array to comments.xml content. Returns a valid empty
-* `<w:comments/>` document for an empty array so callers can overwrite an
-* existing `word/comments.xml` part when the editor has removed the last
-* comment — leaving the previous file in place would otherwise re-emit
-* the orphaned comment threads on every save.
-*/
-function serializeComments(comments, sourceBindings) {
-	const topLevel = [];
-	const replies = [];
-	for (const c of comments) {
-		const { parentId } = c;
-		(parentId === null || parentId === void 0 ? topLevel : replies).push(c);
-	}
-	const body = topLevel.map((comment) => serializeComment(comment)).join("") + replies.map((reply) => serializeComment(reply)).join("");
-	return XML_DECLARATION + serializePartElement({
-		partPath: "word/comments.xml",
-		rootName: "w:comments",
-		baselinePrefixes: COMMENTS_BASELINE_PREFIXES,
-		sourceBindings,
-		body
-	});
-}
-/** The `w14:paraId` Word threads a comment by: its LAST paragraph's paraId. */
-function commentThreadParaId(comment) {
-	return comment.content?.at(-1)?.paraId;
-}
-/**
 * The ids of comments that need a `commentsExtended.xml` entry: a reply, a
 * reply's parent (the thread root), or any comment carrying a resolved state.
 * A plain top-level comment set yields an empty set, so no part is written.
@@ -108,29 +82,71 @@ const commentPlainText = (comment) => {
 	return text;
 };
 /**
-* Assign a deterministic `w14:paraId` to the LAST paragraph of every comment
-* that needs a commentsExtended entry (a reply, a reply's parent, or a resolved
-* comment) but has none. A document authored or loaded without comment paraIds
-* would otherwise have no stable key to thread through commentsExtended.xml, and
-* the thread link would be silently dropped. Word-authored ids are preserved;
-* only threaded, id-less paragraphs are filled. Deterministic (content- and
-* id-derived) so repeated saves mint the SAME id. MUST run before serializing
-* BOTH comments.xml and commentsExtended.xml so the two reference the same id.
+* Plan both comment parts from the model, in the model's own order.
+*
+* The order is the document's: the order `word/comments.xml` listed the
+* comments in is the order it is written back in, so a save neither reshuffles
+* a reviewer's threads nor hands the next parse a different `comments[]` than
+* the one it read.
+*
+* Planning also mints the `w14:paraId` a thread needs when the model has none —
+* a comment written in the editor has no Word-authored id, and without one the
+* `commentsExtended.xml` link would be dropped. Minting is deterministic
+* (comment id and text derived) so repeated saves mint the same id, and it
+* happens here rather than at each call site because both parts must see it.
 */
-function ensureThreadedCommentParaIds(comments) {
-	const threaded = threadedCommentIds(comments);
-	if (threaded.size === 0) return;
-	const used = /* @__PURE__ */ new Set();
-	for (const comment of comments) for (const paragraph of comment.content ?? []) if (paragraph.paraId) used.add(paragraph.paraId.toUpperCase());
+const planCommentParts = (comments) => {
+	const byId = /* @__PURE__ */ new Map();
+	const order = [];
 	for (const comment of comments) {
-		if (!threaded.has(comment.id)) continue;
+		if (byId.has(comment.id)) continue;
+		byId.set(comment.id, comment);
+		order.push(comment.id);
+	}
+	const planned = [...byId.values()];
+	const threadedIds = threadedCommentIds(planned);
+	const used = /* @__PURE__ */ new Set();
+	for (const comment of planned) for (const paragraph of comment.content ?? []) if (paragraph.paraId) used.add(paragraph.paraId.toUpperCase());
+	const threadParaIdById = /* @__PURE__ */ new Map();
+	for (const id of order) {
+		const comment = byId.get(id);
+		const existing = commentThreadParaId((comment.content ?? []).map(({ paraId }) => paraId));
+		if (existing) {
+			threadParaIdById.set(id, existing);
+			continue;
+		}
 		const last = (comment.content ?? []).at(-1);
-		if (!last || last.paraId) continue;
-		let paraId = deterministicHexId(`comment:${comment.id}:${commentPlainText(comment)}`);
-		for (let salt = 1; used.has(paraId.toUpperCase()); salt++) paraId = deterministicHexId(`comment:${comment.id}:${salt}`);
-		used.add(paraId.toUpperCase());
-		last.paraId = paraId;
+		if (!threadedIds.has(id) || !last) continue;
+		let minted = deterministicHexId(`comment:${id}:${commentPlainText(comment)}`);
+		for (let salt = 1; used.has(minted.toUpperCase()); salt++) minted = deterministicHexId(`comment:${id}:${salt}`);
+		used.add(minted.toUpperCase());
+		last.paraId = minted;
+		threadParaIdById.set(id, minted);
 	}
+	return {
+		order,
+		byId,
+		threadParaIdById,
+		threadedIds
+	};
+};
+/**
+* Serialize a comment plan to comments.xml content. Returns a valid empty
+* `<w:comments/>` document for an empty plan so callers can overwrite an
+* existing `word/comments.xml` part when the editor has removed the last
+* comment — leaving the previous file in place would otherwise re-emit
+* the orphaned comment threads on every save.
+*/
+function serializeComments({ order, byId }, sourceBindings) {
+	let body = "";
+	for (const id of order) body += serializeComment(byId.get(id));
+	return XML_DECLARATION + serializePartElement({
+		partPath: "word/comments.xml",
+		rootName: "w:comments",
+		baselinePrefixes: COMMENTS_BASELINE_PREFIXES,
+		sourceBindings,
+		body
+	});
 }
 /**
 * Build the `commentsExtended.xml` entries for the comments that participate in
@@ -139,29 +155,23 @@ function ensureThreadedCommentParaIds(comments) {
 * leave any existing part untouched — a plain top-level comment set gets no
 * `commentsExtended.xml`, matching how Word omits it.
 *
-* A `w15:commentEx` keys on the comment's LAST paragraph paraId; a reply's
-* `w15:paraIdParent` points at its parent comment's last-paragraph paraId. Ids
-* are guaranteed present by {@link ensureThreadedCommentParaIds}; the `!paraId`
-* skip is a last-ditch safety for a malformed model.
+* A `w15:commentEx` keys on the comment's thread paraId; a reply's
+* `w15:paraIdParent` on its parent's. Both come from the plan, so a reply and
+* its parent name each other by `w:id` right up to the attribute.
 */
-function buildCommentExtendedEntries(comments) {
-	const threaded = threadedCommentIds(comments);
-	if (threaded.size === 0) return null;
-	const paraIdByCommentId = /* @__PURE__ */ new Map();
-	for (const comment of comments) {
-		const paraId = commentThreadParaId(comment);
-		if (paraId) paraIdByCommentId.set(comment.id, paraId);
-	}
+function buildCommentExtendedEntries({ order, byId, threadParaIdById, threadedIds }) {
+	if (threadedIds.size === 0) return null;
 	const entries = [];
-	for (const comment of comments) {
-		if (!threaded.has(comment.id)) continue;
-		const paraId = paraIdByCommentId.get(comment.id);
+	for (const id of order) {
+		if (!threadedIds.has(id)) continue;
+		const paraId = threadParaIdById.get(id);
 		if (!paraId) continue;
-		const parentParaId = comment.parentId !== void 0 ? paraIdByCommentId.get(comment.parentId) : void 0;
+		const { parentId, done } = byId.get(id);
+		const parentParaId = parentId !== void 0 ? threadParaIdById.get(parentId) : void 0;
 		entries.push({
 			paraId,
 			...parentParaId !== void 0 ? { paraIdParent: parentParaId } : {},
-			done: comment.done ?? false
+			done: done ?? false
 		});
 	}
 	return entries.length > 0 ? entries : null;
@@ -172,12 +182,12 @@ function buildCommentExtendedEntries(comments) {
 * {@link buildCommentExtendedEntries}). This is the part that makes Word render
 * a comment as a REPLY rather than a separate top-level thread.
 */
-function serializeCommentsExtended(comments) {
-	const entries = buildCommentExtendedEntries(comments);
+function serializeCommentsExtended(plan) {
+	const entries = buildCommentExtendedEntries(plan);
 	if (!entries) return null;
 	const body = entries.map((entry) => {
-		const parentAttr = entry.paraIdParent !== void 0 ? ` w15:paraIdParent="${escapeXml(entry.paraIdParent)}"` : "";
-		return `<w15:commentEx w15:paraId="${escapeXml(entry.paraId)}"${parentAttr} w15:done="${entry.done ? "1" : "0"}"/>`;
+		const parentAttr = entry.paraIdParent !== void 0 ? ` w15:paraIdParent="${escapeXmlAttribute(entry.paraIdParent)}"` : "";
+		return `<w15:commentEx w15:paraId="${escapeXmlAttribute(entry.paraId)}"${parentAttr} w15:done="${entry.done ? "1" : "0"}"/>`;
 	}).join("");
 	return XML_DECLARATION + serializePartElement({
 		partPath: "word/commentsExtended.xml",
@@ -188,4 +198,4 @@ function serializeCommentsExtended(comments) {
 	});
 }
 //#endregion
-export { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended };
+export { planCommentParts, serializeComments, serializeCommentsExtended };

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

@@ -47,10 +47,6 @@ declare function getDocumentParagraphCount(doc: document_d_exports.Document): nu
  * Get table count in document
  */
 declare function getDocumentTableCount(doc: document_d_exports.Document): number;
-/**
- * Get plain text from document (for comparison/debugging)
- */
-declare function getDocumentPlainText(doc: document_d_exports.Document): string;
 /**
  * Create an empty document
  */
@@ -63,4 +59,4 @@ declare function createSimpleDocument(paragraphs: {
   styleId?: string;
 }[]): document_d_exports.Document;
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentPlainText, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/documentSerializer.js

@@ -1,3 +1,4 @@
+import { withBlockRangeMarkers } from "../blockRangeMarkers.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
@@ -40,6 +41,10 @@ const DOCUMENT_BASELINE_PREFIXES = [
 * Serialize a single block content item (paragraph, table, or block-level SDT).
 */
 function serializeBlockContent(block) {
+	return withBlockRangeMarkers(block, serializeBlockBody(block));
+}
+/** The block itself, without the range markers that stood around it. */
+function serializeBlockBody(block) {
 	if (block.type === "paragraph") return serializeParagraph(block);
 	if (block.type === "table") return serializeTable(block, serializeParagraph);
 	return serializeBlockSdt(block, serializeBlockContent);
@@ -127,21 +132,6 @@ function getDocumentTableCount(doc) {
 	return doc.package.document.content.filter((b) => b.type === "table").length;
 }
 /**
-* Get plain text from document (for comparison/debugging)
-*/
-function getDocumentPlainText(doc) {
-	const texts = [];
-	for (const block of doc.package.document.content) if (block.type === "paragraph") {
-		for (const content of block.content) if (content.type === "run") {
-			for (const item of content.content) if (item.type === "text") texts.push(item.text);
-			else if (item.type === "tab") texts.push("	");
-			else if (item.type === "break") texts.push("\n");
-		}
-		texts.push("\n");
-	}
-	return texts.join("");
-}
-/**
 * Create an empty document
 */
 function createEmptyDocument() {
@@ -164,4 +154,4 @@ function createSimpleDocument(paragraphs) {
 	})) } } };
 }
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentPlainText, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/fontTableSerializer.js

@@ -1,5 +1,5 @@
 import { serializePartElement } from "./partNamespaces.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/fontTableSerializer.ts
 const serializeFontTableXml = (fontTable) => "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
 	partPath: "word/fontTable.xml",
@@ -10,20 +10,20 @@ const serializeFontTableXml = (fontTable) => "<?xml version=\"1.0\" encoding=\"U
 });
 const serializeFont = (font) => {
 	const parts = [];
-	if (font.altName) parts.push(`<w:altName w:val="${escapeXml(font.altName)}"/>`);
-	if (font.panose1) parts.push(`<w:panose1 w:val="${escapeXml(font.panose1)}"/>`);
-	if (font.charset) parts.push(`<w:charset w:val="${escapeXml(font.charset)}"/>`);
+	if (font.altName) parts.push(`<w:altName w:val="${escapeXmlAttribute(font.altName)}"/>`);
+	if (font.panose1) parts.push(`<w:panose1 w:val="${escapeXmlAttribute(font.panose1)}"/>`);
+	if (font.charset) parts.push(`<w:charset w:val="${escapeXmlAttribute(font.charset)}"/>`);
 	if (font.family) parts.push(`<w:family w:val="${font.family}"/>`);
 	if (font.pitch) parts.push(`<w:pitch w:val="${font.pitch}"/>`);
 	if (font.sig) {
 		const attrs = [];
 		for (const [key, value] of Object.entries(font.sig)) {
 			if (value === void 0) continue;
-			attrs.push(`w:${key}="${escapeXml(value)}"`);
+			attrs.push(`w:${key}="${escapeXmlAttribute(value)}"`);
 		}
 		if (attrs.length > 0) parts.push(`<w:sig ${attrs.join(" ")}/>`);
 	}
-	return `<w:font w:name="${escapeXml(font.name)}">${parts.join("")}</w:font>`;
+	return `<w:font w:name="${escapeXmlAttribute(font.name)}">${parts.join("")}</w:font>`;
 };
 //#endregion
 export { serializeFontTableXml };

package/dist/docx/serializer/headerFooterSerializer.js

@@ -1,3 +1,4 @@
+import { withBlockRangeMarkers } from "../blockRangeMarkers.js";
 import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
 import { isEmptyParagraph } from "../paragraphParser.js";
 import { captureVerbatimXml } from "../verbatimCapture.js";
@@ -6,7 +7,7 @@ import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTable } from "./tableSerializer.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/headerFooterSerializer.ts
 const HEADER_FOOTER_BASELINE_PREFIXES = [
 	"wpc",
@@ -36,6 +37,10 @@ const HEADER_FOOTER_BASELINE_PREFIXES = [
 * header/footer.
 */
 function serializeBlock(block) {
+	return withBlockRangeMarkers(block, serializeBlockBody(block));
+}
+/** The block itself, without the range markers that stood around it. */
+function serializeBlockBody(block) {
 	if (block.type === "paragraph") return serializeParagraph(block);
 	if (block.type === "table") return serializeTable(block, serializeParagraph);
 	return serializeBlockSdt(block, serializeBlock);
@@ -80,7 +85,7 @@ function serializeRawWatermarkIntoHost({ hostXml, rawWatermarkXml }) {
 	if (!rawHost || getLocalName(rawHost.name ?? "") !== "p") return rawWatermarkXml;
 	const watermarkContent = (rawHost.elements ?? []).filter((child) => child.type === "element" && getLocalName(child.name ?? "") !== "pPr").map((child) => captureVerbatimXml(child)).join("");
 	if (!watermarkContent) return rawWatermarkXml;
-	const namespaceAttributes = Object.entries(rawHost.attributes ?? {}).filter(([name, value]) => value !== void 0 && (name === "xmlns" || name.startsWith("xmlns:"))).map(([name, value]) => ` ${name}="${escapeXml(String(value))}"`).join("");
+	const namespaceAttributes = Object.entries(rawHost.attributes ?? {}).filter(([name, value]) => value !== void 0 && (name === "xmlns" || name.startsWith("xmlns:"))).map(([name, value]) => ` ${name}="${escapeXmlAttribute(String(value))}"`).join("");
 	return hostXml.replace(/^<w:p(?=[\s>])/u, `<w:p${namespaceAttributes}`).replace("</w:p>", `${watermarkContent}</w:p>`);
 }
 function serializeWatermarkParagraph(hf) {
@@ -96,15 +101,15 @@ function synthesizeTextWatermark(watermark) {
 	const rotation = watermark.diagonal === false ? 0 : 315;
 	const fillcolor = watermark.color && watermark.color !== "auto" ? `#${watermark.color}` : "#C0C0C0";
 	const fontFamily = watermark.font ?? "Calibri";
-	const text = escapeXml(watermark.text);
-	return `<w:p><w:r><w:pict><v:shape id="PowerPlusWaterMarkObject1" type="#_x0000_t136" style="position:absolute;margin-left:0;margin-top:0;width:415pt;height:207pt;rotation:${rotation};z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin" fillcolor="${fillcolor}" stroked="f">${watermark.opacity !== void 0 ? `<v:fill opacity="${watermark.opacity}"/>` : ""}<v:textpath style="font-family:&quot;${escapeXml(fontFamily)}&quot;;font-size:1pt" string="${text}"/></v:shape></w:pict></w:r></w:p>`;
+	const text = escapeXmlAttribute(watermark.text);
+	return `<w:p><w:r><w:pict><v:shape id="PowerPlusWaterMarkObject1" type="#_x0000_t136" style="position:absolute;margin-left:0;margin-top:0;width:415pt;height:207pt;rotation:${rotation};z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin" fillcolor="${fillcolor}" stroked="f">${watermark.opacity !== void 0 ? `<v:fill opacity="${watermark.opacity}"/>` : ""}<v:textpath style="font-family:&quot;${escapeXmlAttribute(fontFamily)}&quot;;font-size:1pt" string="${text}"/></v:shape></w:pict></w:r></w:p>`;
 }
 const PICTURE_WATERMARK_DEFAULT_WIDTH_PT = 415;
 const PICTURE_WATERMARK_DEFAULT_HEIGHT_PT = 207;
 const PICTURE_WATERMARK_WASHOUT_GAIN = "19661f";
 const PICTURE_WATERMARK_WASHOUT_BLACKLEVEL = "22938f";
 function synthesizePictureWatermark(watermark) {
-	const rId = escapeXml(watermark.imageRId);
+	const rId = escapeXmlAttribute(watermark.imageRId);
 	return `<w:p><w:r><w:pict><v:shape id="WordPictureWatermark1" type="#_x0000_t75" style="position:absolute;margin-left:0;margin-top:0;width:${watermark.scale === void 0 ? watermark.widthPt ?? PICTURE_WATERMARK_DEFAULT_WIDTH_PT : PICTURE_WATERMARK_DEFAULT_WIDTH_PT * watermark.scale}pt;height:${watermark.scale === void 0 ? watermark.heightPt ?? PICTURE_WATERMARK_DEFAULT_HEIGHT_PT : PICTURE_WATERMARK_DEFAULT_HEIGHT_PT * watermark.scale}pt;z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin"><v:imagedata r:id="${rId}" o:title=""${watermark.washout === false ? "" : ` gain="${PICTURE_WATERMARK_WASHOUT_GAIN}" blacklevel="${PICTURE_WATERMARK_WASHOUT_BLACKLEVEL}"`}/></v:shape></w:pict></w:r></w:p>`;
 }
 //#endregion

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

@@ -0,0 +1,8 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/serializer/markupRangeAttributes.d.ts
+declare const markupRangeAttributes: (marker: document_d_exports.MarkupRangeMarker) => string[];
+declare const bookmarkRangeAttributes: (marker: document_d_exports.BookmarkRangeMarker) => string[];
+/** `w:author` is required, so it is always written; `w:date` only when known. */
+declare const moveBookmarkAttributes: (marker: document_d_exports.MoveBookmarkMarker) => string[];
+//#endregion
+export { bookmarkRangeAttributes, markupRangeAttributes, moveBookmarkAttributes };

package/dist/docx/serializer/markupRangeAttributes.js

@@ -0,0 +1,24 @@
+import { escapeXmlAttribute } from "@stll/docx-core";
+//#region src/docx/serializer/markupRangeAttributes.ts
+const attribute = (name, value) => `${name}="${escapeXmlAttribute(String(value))}"`;
+const markupRangeAttributes = (marker) => {
+	const attributes = [attribute("w:id", marker.id)];
+	if (marker.displacedByCustomXml !== void 0) attributes.push(attribute("w:displacedByCustomXml", marker.displacedByCustomXml));
+	return attributes;
+};
+const bookmarkRangeAttributes = (marker) => {
+	const attributes = markupRangeAttributes(marker);
+	if (marker.colFirst !== void 0) attributes.push(attribute("w:colFirst", marker.colFirst));
+	if (marker.colLast !== void 0) attributes.push(attribute("w:colLast", marker.colLast));
+	attributes.push(attribute("w:name", marker.name));
+	return attributes;
+};
+/** `w:author` is required, so it is always written; `w:date` only when known. */
+const moveBookmarkAttributes = (marker) => {
+	const attributes = bookmarkRangeAttributes(marker);
+	attributes.push(attribute("w:author", marker.author.trim() || "Unknown"));
+	if (marker.date !== void 0 && marker.date.trim().length > 0) attributes.push(attribute("w:date", marker.date.trim()));
+	return attributes;
+};
+//#endregion
+export { bookmarkRangeAttributes, markupRangeAttributes, moveBookmarkAttributes };

package/dist/docx/serializer/noteSerializer.js

@@ -1,3 +1,4 @@
+import { withBlockRangeMarkers } from "../blockRangeMarkers.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
@@ -38,6 +39,10 @@ const serializeNotePart = (elementName, body) => "<?xml version=\"1.0\" encoding
 * note body.
 */
 function serializeBlock(block) {
+	return withBlockRangeMarkers(block, serializeBlockBody(block));
+}
+/** The block itself, without the range markers that stood around it. */
+function serializeBlockBody(block) {
 	if (block.type === "paragraph") return serializeParagraph(block);
 	if (block.type === "table") return serializeTable(block, serializeParagraph);
 	return serializeBlockSdt(block, serializeBlock);

package/dist/docx/serializer/numberingSerializer.js

@@ -1,6 +1,7 @@
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/numberingSerializer.ts
 /**
 * Serialize a level's paragraph properties — the modeled subset is indentation
@@ -36,11 +37,11 @@ function serializeLevelParagraphProps(pPr) {
 function serializeLevel(level) {
 	const parts = [];
 	if (level.start !== void 0) parts.push(`<w:start w:val="${intAttr(level.start)}"/>`);
-	parts.push(`<w:numFmt w:val="${escapeXml(level.numFmt)}"/>`);
+	parts.push(`<w:numFmt w:val="${escapeXmlAttribute(level.numFmt)}"/>`);
 	if (level.lvlRestart !== void 0) parts.push(`<w:lvlRestart w:val="${intAttr(level.lvlRestart)}"/>`);
 	if (level.isLgl) parts.push("<w:isLgl/>");
 	if (level.suffix) parts.push(`<w:suff w:val="${level.suffix}"/>`);
-	parts.push(`<w:lvlText w:val="${escapeXml(level.lvlText)}"/>`);
+	parts.push(`<w:lvlText w:val="${escapeXmlAttribute(level.lvlText)}"/>`);
 	if (level.legacy) {
 		const legacyAttrs = [`w:legacy="${level.legacy.legacy ? 1 : 0}"`];
 		if (level.legacy.legacySpace !== void 0) legacyAttrs.push(`w:legacySpace="${intAttr(level.legacy.legacySpace)}"`);
@@ -60,9 +61,9 @@ function serializeLevel(level) {
 function serializeAbstractNum(abstractNum) {
 	const parts = [];
 	if (abstractNum.multiLevelType) parts.push(`<w:multiLevelType w:val="${abstractNum.multiLevelType}"/>`);
-	if (abstractNum.name !== void 0) parts.push(`<w:name w:val="${escapeXml(abstractNum.name)}"/>`);
-	if (abstractNum.styleLink !== void 0) parts.push(`<w:styleLink w:val="${escapeXml(abstractNum.styleLink)}"/>`);
-	if (abstractNum.numStyleLink !== void 0) parts.push(`<w:numStyleLink w:val="${escapeXml(abstractNum.numStyleLink)}"/>`);
+	if (abstractNum.name !== void 0) parts.push(`<w:name w:val="${escapeXmlAttribute(abstractNum.name)}"/>`);
+	if (abstractNum.styleLink !== void 0) parts.push(`<w:styleLink w:val="${escapeXmlAttribute(abstractNum.styleLink)}"/>`);
+	if (abstractNum.numStyleLink !== void 0) parts.push(`<w:numStyleLink w:val="${escapeXmlAttribute(abstractNum.numStyleLink)}"/>`);
 	const levels = [...abstractNum.levels].sort((a, b) => a.ilvl - b.ilvl);
 	for (const level of levels) parts.push(serializeLevel(level));
 	return `<w:abstractNum w:abstractNumId="${intAttr(abstractNum.abstractNumId)}">${parts.join("")}</w:abstractNum>`;

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

@@ -23,10 +23,6 @@ declare function hasParagraphContent(paragraph: document_d_exports.Paragraph): b
  * Check if a paragraph has formatting
  */
 declare function hasParagraphFormatting(paragraph: document_d_exports.Paragraph): boolean;
-/**
- * Get plain text from a paragraph (for comparison/debugging)
- */
-declare function getParagraphPlainText(paragraph: document_d_exports.Paragraph): string;
 /**
  * Create an empty paragraph
  */
@@ -44,4 +40,4 @@ declare function isListParagraph(paragraph: document_d_exports.Paragraph): boole
  */
 declare function getListLevel(paragraph: document_d_exports.Paragraph): number;
 //#endregion
-export { createEmptyParagraph, createTextParagraph, getListLevel, getParagraphPlainText, hasParagraphContent, hasParagraphFormatting, isListParagraph, serializeParagraph, serializeParagraphFormatting, serializeParagraphs };
+export { createEmptyParagraph, createTextParagraph, getListLevel, hasParagraphContent, hasParagraphFormatting, isListParagraph, serializeParagraph, serializeParagraphFormatting, serializeParagraphs };