@stll/folio-core 0.45.0 → 0.46.0

package/dist/docx/paragraphPropertySource.js

@@ -262,10 +262,11 @@ const invalidTableCellParagraphSourcePayload = (classification, path) => {
 const tableCellBlockTraversalByType = {
 	blockSdt: "blockSdt",
 	paragraph: "paragraph",
+	preservedBlock: "leaf",
 	table: "table"
 };
 const tableCellParagraphContentTraversalByType = {
-	bidiWrapper: "content",
+	inlineWrapper: "content",
 	bookmarkEnd: "leaf",
 	bookmarkStart: "leaf",
 	commentRangeEnd: "leaf",
@@ -283,6 +284,7 @@ const tableCellParagraphContentTraversalByType = {
 	moveTo: "content",
 	moveToRangeEnd: "leaf",
 	moveToRangeStart: "leaf",
+	preservedInline: "leaf",
 	run: "run",
 	simpleField: "content"
 };
@@ -294,6 +296,7 @@ const tableCellRunContentTraversalByType = {
 	footnoteRef: "leaf",
 	instrText: "leaf",
 	noBreakHyphen: "leaf",
+	preservedXml: "leaf",
 	renderedPageBreak: "leaf",
 	shape: "shape",
 	softHyphen: "leaf",
@@ -453,6 +456,7 @@ function visitDecodedTableCellBlock(value, path, context) {
 			for (const [index, child] of content.entries()) visitDecodedTableCellBlock(child, `${path}.content[${index}]`, context);
 			return;
 		}
+		case "leaf": return;
 		default: return traversal;
 	}
 }

package/dist/docx/paragraphTextBoxEnrichment.d.ts

@@ -1,7 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 import { TableParserFn } from "./textBoxParser.js";
 //#region src/docx/paragraphTextBoxEnrichment.d.ts
 declare const enrichParagraphTextBoxes: (paragraph: document_d_exports.Paragraph, paraXml: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, parseTable: TableParserFn) => void;

package/dist/docx/paragraphTextBoxEnrichment.js

@@ -1,6 +1,7 @@
 import { pixelsToEmu } from "../utils/units.js";
 import { parseParagraph } from "./paragraphParser.js";
-import { getTextBoxContentElement, isTextBoxDrawing, parseTextBox, parseTextBoxContent } from "./textBoxParser.js";
+import { getTextBoxContentElement, parseTextBox, parseTextBoxContent, scanRunForTextBoxDrawings } from "./textBoxParser.js";
+import { isVmlPictParsedByRunParser } from "./vmlImageParser.js";
 import { findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/paragraphTextBoxEnrichment.ts
 const VML_HORIZONTAL_RELATIVES = /* @__PURE__ */ new Set([
@@ -182,7 +183,10 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 			if (parsedIndex < content.length && parsedContent?.type !== "run") parsedIndex += 1;
 			continue;
 		}
-		const { textBoxDrawings, vmlTextBoxes, hasNonTextBoxContent } = scanRunForTextBoxDrawings(xmlChild);
+		const { textBoxDrawings, vmlTextBoxes, hasNonTextBoxContent } = scanRunForTextBoxDrawings({
+			xmlRun: xmlChild,
+			claimedByRunParser: (pictElement) => isVmlPictParsedByRunParser(pictElement, rels, media)
+		});
 		const parsedRun = parsedContent?.type === "run" ? parsedContent : void 0;
 		const targetRun = parsedRun ?? (hasNonTextBoxContent ? lastConsumedRun : void 0);
 		const targetRunMatchesXml = targetRun !== void 0 && (hasNonTextBoxContent || parsedRun?.content.length === 0);
@@ -254,56 +258,6 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 		}
 	}
 };
-const scanRunForTextBoxDrawings = (xmlRun) => {
-	const textBoxDrawings = [];
-	const vmlTextBoxes = [];
-	let hasNonTextBoxContent = false;
-	const visitDrawing = (drawingEl) => {
-		if (isTextBoxDrawing(drawingEl)) {
-			textBoxDrawings.push(drawingEl);
-			return;
-		}
-		hasNonTextBoxContent = true;
-	};
-	for (const el of getChildElements(xmlRun)) {
-		const name = getLocalName(el.name ?? "");
-		if (name === "rPr") continue;
-		if (name === "drawing") {
-			visitDrawing(el);
-			continue;
-		}
-		if (name === "pict") {
-			if (findDeep(el, "v", "textbox")) if (findDeep(el, "v", "imagedata")) hasNonTextBoxContent = true;
-			else vmlTextBoxes.push(el);
-			else hasNonTextBoxContent = true;
-			continue;
-		}
-		if (name === "AlternateContent") {
-			const branches = getChildElements(el);
-			const choice = branches.find((branch) => getLocalName(branch.name ?? "") === "Choice");
-			const fallback = branches.find((branch) => getLocalName(branch.name ?? "") === "Fallback");
-			const tryBranch = (branch) => {
-				if (!branch) return false;
-				let found = false;
-				for (const innerEl of getChildElements(branch)) if (getLocalName(innerEl.name ?? "") === "drawing") {
-					visitDrawing(innerEl);
-					found = true;
-				}
-				return found;
-			};
-			let foundInBranch = tryBranch(choice);
-			if (!foundInBranch) foundInBranch = tryBranch(fallback);
-			if (!foundInBranch) hasNonTextBoxContent = true;
-			continue;
-		}
-		hasNonTextBoxContent = true;
-	}
-	return {
-		textBoxDrawings,
-		vmlTextBoxes,
-		hasNonTextBoxContent
-	};
-};
 const parseVmlTextBoxShape = (pictEl, styles, theme, numbering, rels, media, parseTable) => {
 	const shapeEl = findDeep(pictEl, "v", "shape");
 	const textBoxEl = shapeEl ? findDeep(shapeEl, "v", "textbox") : null;

package/dist/docx/paragraphTraversal.js

@@ -16,7 +16,7 @@ const visitParagraphRuns = (paragraph, visit) => {
 			case "moveFrom":
 			case "moveTo":
 			case "inlineSdt":
-			case "bidiWrapper":
+			case "inlineWrapper":
 				for (const child of content.content) visitParagraphContent(child);
 				return;
 			case "complexField":
@@ -32,7 +32,8 @@ const visitParagraphRuns = (paragraph, visit) => {
 			case "moveFromRangeEnd":
 			case "moveToRangeStart":
 			case "moveToRangeEnd":
-			case "mathEquation": return;
+			case "mathEquation":
+			case "preservedInline": return;
 			default: return content;
 		}
 	};
@@ -69,7 +70,7 @@ const visitInlineContentSlots = (paragraph, visit) => {
 				case "deletion":
 				case "moveFrom":
 				case "moveTo":
-				case "bidiWrapper":
+				case "inlineWrapper":
 					visitContent(item.content);
 					break;
 				case "run":
@@ -83,7 +84,8 @@ const visitInlineContentSlots = (paragraph, visit) => {
 				case "moveFromRangeEnd":
 				case "moveToRangeStart":
 				case "moveToRangeEnd":
-				case "mathEquation": break;
+				case "mathEquation":
+				case "preservedInline": break;
 				default: panic(`Unsupported paragraph content: ${JSON.stringify(item)}`);
 			}
 		}
@@ -145,6 +147,7 @@ const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnot
 			visitTable(block);
 			return;
 		}
+		if (block.type === "preservedBlock") return;
 		visitBlocks(block.content);
 	};
 	const visitBlocks = (blocks) => {

package/dist/docx/parseWarningMessage.js

@@ -36,7 +36,8 @@ const PARSE_WARNING_MESSAGES = {
 	[PARSE_WARNING_CODES.unrecognisedOnOffValue]: (warning) => `Ignored on/off value${quoted(warning.value)}${where(warning)}; ST_OnOff is 1, 0, true, false, on or off.`,
 	[PARSE_WARNING_CODES.borderWithoutValue]: (warning) => `Read a border with no w:val${where(warning)} as having no border style.`,
 	[PARSE_WARNING_CODES.styleSetDuplicateStyleId]: (warning) => `Dropped a style repeating the id${quoted(warning.value)} another style in the set already defines.`,
-	[PARSE_WARNING_CODES.styleSetInitialStyleMissing]: (warning) => `The style set names initial paragraph style${quoted(warning.value)}, which it does not contain; used the set's default instead${where(warning)}.`
+	[PARSE_WARNING_CODES.styleSetInitialStyleMissing]: (warning) => `The style set names initial paragraph style${quoted(warning.value)}, which it does not contain; used the set's default instead${where(warning)}.`,
+	[PARSE_WARNING_CODES.pageBreakProjectionApproximated]: (warning) => `${warning.detail ?? "An explicit page break is laid out approximately"}${where(warning)}.`
 };
 const formatParseWarning = (warning) => PARSE_WARNING_MESSAGES[warning.code](warning);
 const formatParseWarnings = (warnings) => warnings.map(formatParseWarning);

package/dist/docx/preservedRunContent.d.ts

@@ -0,0 +1,32 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/preservedRunContent.d.ts
+/**
+ * The visible text a preserved run child contributes, or `""` when it shows
+ * nothing. Unknown markup contributes nothing on purpose: guessing at the text
+ * of an element folio has never seen would put invented words in a document.
+ */
+declare const preservedRunChildText: (element: XmlElement) => string;
+/**
+ * Capture one unmodelled run child.
+ *
+ * `captureVerbatimXml` materialises exactly the namespace bindings the
+ * fragment's own prefixes need and leaves the canonical ones to the rebuilt
+ * root, so ordinary `w:` markup comes back byte for byte while a foreign
+ * prefix still arrives bound. Copying the whole root scope onto the fragment
+ * instead would rewrite every capture with declarations it does not use.
+ */
+declare const preserveRunChild: (element: XmlElement) => document_d_exports.PreservedXmlContent;
+/**
+ * One capture from the shared dispatcher's sink, as a member of the
+ * container's own inline union.
+ *
+ * The sink holds markup the schema does not declare for the container at all,
+ * so nothing is known about it beyond its bytes: `text` is empty because a
+ * name folio has never seen shows nothing folio can read.
+ */
+declare const preservedInlineCapture: (xml: string) => document_d_exports.PreservedInline;
+/** Capture one unmodelled inline child of a paragraph or an inline wrapper. */
+declare const preserveInlineChild: (element: XmlElement) => document_d_exports.PreservedInline;
+//#endregion
+export { preserveInlineChild, preserveRunChild, preservedInlineCapture, preservedRunChildText };

package/dist/docx/preservedRunContent.js

@@ -0,0 +1,86 @@
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChildrenByLocalName, getChildElements, getLocalName, getTextContent } from "./xmlParser.js";
+//#region src/docx/preservedRunContent.ts
+/**
+* Where a preserved run child hides text a reader sees, by local name: the
+* child elements whose `w:t` descendants are on the line rather than above,
+* beside, or nowhere.
+*
+* `w:ruby` is the whole list today. Its `w:rt` is the annotation printed above
+* the base and is not the sentence's text; its `w:rubyBase` is.
+*/
+const VISIBLE_TEXT_CHILDREN = /* @__PURE__ */ new Map([["ruby", ["rubyBase"]]]);
+/** Cap on the text one preserved child contributes, mirroring `w:t` handling. */
+const MAX_PRESERVED_TEXT_LENGTH = 1e5;
+const collectTextContent = (element, into) => {
+	for (const child of getChildElements(element)) {
+		if (getLocalName(child.name) === "t") {
+			into.push(getTextContent(child));
+			continue;
+		}
+		collectTextContent(child, into);
+	}
+};
+/**
+* The visible text a preserved run child contributes, or `""` when it shows
+* nothing. Unknown markup contributes nothing on purpose: guessing at the text
+* of an element folio has never seen would put invented words in a document.
+*/
+const preservedRunChildText = (element) => {
+	const sources = VISIBLE_TEXT_CHILDREN.get(getLocalName(element.name));
+	if (sources === void 0) return "";
+	const parts = [];
+	for (const localName of sources) for (const source of findChildrenByLocalName(element, localName)) collectTextContent(source, parts);
+	return parts.join("").slice(0, MAX_PRESERVED_TEXT_LENGTH);
+};
+/**
+* Capture one unmodelled run child.
+*
+* `captureVerbatimXml` materialises exactly the namespace bindings the
+* fragment's own prefixes need and leaves the canonical ones to the rebuilt
+* root, so ordinary `w:` markup comes back byte for byte while a foreign
+* prefix still arrives bound. Copying the whole root scope onto the fragment
+* instead would rewrite every capture with declarations it does not use.
+*/
+const preserveRunChild = (element) => ({
+	type: "preservedXml",
+	xml: captureVerbatimXml(element),
+	text: preservedRunChildText(element)
+});
+/**
+* Where an unmodelled *inline* child hides text a reader sees, by local name.
+*
+* `w:customXml` and `w:smartTag` are transparent wrappers (ECMA-376 §17.5.1,
+* §17.5.1.9): their content is ordinary inline content, so their `w:t`
+* descendants are on the line. Every other inline child folio captures —
+* `w:permStart`, `w:proofErr` and the custom-XML revision ranges — is an
+* empty marker, and an element folio has never seen contributes nothing on
+* purpose, because guessing at its text would put invented words in a
+* document.
+*/
+const VISIBLE_TEXT_INLINE_CHILDREN = /* @__PURE__ */ new Set(["customXml", "smartTag"]);
+/**
+* One capture from the shared dispatcher's sink, as a member of the
+* container's own inline union.
+*
+* The sink holds markup the schema does not declare for the container at all,
+* so nothing is known about it beyond its bytes: `text` is empty because a
+* name folio has never seen shows nothing folio can read.
+*/
+const preservedInlineCapture = (xml) => ({
+	type: "preservedInline",
+	xml,
+	text: ""
+});
+/** Capture one unmodelled inline child of a paragraph or an inline wrapper. */
+const preserveInlineChild = (element) => {
+	const parts = [];
+	if (VISIBLE_TEXT_INLINE_CHILDREN.has(getLocalName(element.name))) collectTextContent(element, parts);
+	return {
+		type: "preservedInline",
+		xml: captureVerbatimXml(element),
+		text: parts.join("").slice(0, MAX_PRESERVED_TEXT_LENGTH)
+	};
+};
+//#endregion
+export { preserveInlineChild, preserveRunChild, preservedInlineCapture, preservedRunChildText };

package/dist/docx/renderedPageBreakNormalization.js

@@ -37,9 +37,7 @@ const scanHyperlink = (hyperlink, scan) => {
 };
 const scanInlineContent = (content, scan) => {
 	for (const child of content) {
-		let result;
-		if (child.type === "run") result = scanRun(child, scan);
-		else if (child.type === "hyperlink") result = scanHyperlink(child, scan);
+		const result = scanParagraphContent(child, scan);
 		if (result !== void 0) return result;
 	}
 };
@@ -48,7 +46,7 @@ const scanParagraphContent = (content, scan) => {
 	if (content.type === "hyperlink") return scanHyperlink(content, scan);
 	if (content.type === "simpleField") return scanInlineContent(content.content, scan);
 	if (content.type === "insertion" || content.type === "deletion" || content.type === "moveFrom" || content.type === "moveTo") return scanInlineContent(content.content, scan);
-	if (content.type === "inlineSdt") {
+	if (content.type === "inlineSdt" || content.type === "inlineWrapper") {
 		for (const child of content.content) {
 			const result = scanParagraphContent(child, scan);
 			if (result !== void 0) return result;

package/dist/docx/rezip.js

@@ -29,7 +29,7 @@ import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
-import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
 import { panic } from "better-result";
 import { escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
@@ -443,6 +443,7 @@ function collectHyperlinksWithoutRId(blocks) {
 				break;
 			case "simpleField":
 			case "inlineSdt":
+			case "inlineWrapper":
 			case "insertion":
 			case "deletion":
 			case "moveFrom":
@@ -454,7 +455,7 @@ function collectHyperlinksWithoutRId(blocks) {
 	};
 	for (const block of blocks) if (block.type === "paragraph") collectInlineHyperlinks(block.content);
 	else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) hyperlinks.push(...collectHyperlinksWithoutRId(cell.content));
-	else hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
+	else if (block.type === "blockSdt") hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
 	return hyperlinks;
 }
 /** The selective save boundary must use the same resource census as full repack. */
@@ -1425,7 +1426,26 @@ const seedStylesXmlWith = (missing) => {
 	const rootClose = SEED_STYLES_XML.lastIndexOf(STYLES_CLOSE_ROOT);
 	return SEED_STYLES_XML.slice(0, rootClose) + missing.map(serializeStyle).join("") + SEED_STYLES_XML.slice(rootClose);
 };
-const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
+/**
+* The style ids `word/styles.xml` already defines.
+*
+* Read by parsing the part, because the model holds the *decoded* id and the
+* part holds its XML spelling: `w:styleId='Body A'` is single-quoted,
+* `w:styleId="Header &amp; Footer"` is escaped, and either may sit behind an
+* attribute value containing `>`. A reader that misses one of those reports a
+* style the part already defines as missing, and
+* {@link serializeAddedStylesIntoZip} appends it — on every save, for ever.
+*/
+const definedStyleIds = (stylesXml) => {
+	const root = parseXml(stylesXml);
+	const styles = findChildByNamespaceUri(root, WORDPROCESSINGML_NAMESPACE_URIS, "styles") ?? root;
+	const ids = /* @__PURE__ */ new Set();
+	for (const style of findChildrenByNamespaceUri(styles, WORDPROCESSINGML_NAMESPACE_URIS, "style")) {
+		const id = getAttributeByNamespaceUri(style, WORDPROCESSINGML_NAMESPACE_URIS, "styleId") ?? style.attributes?.["w:styleId"];
+		if (id !== void 0 && id !== null && id !== "") ids.add(String(id));
+	}
+	return ids;
+};
 /**
 * Append styles the model defines but the original `word/styles.xml` lacks.
 * Existing styles stay byte-exact (edits to them are not written here, the
@@ -1471,9 +1491,13 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		});
 		return;
 	}
-	const existing = /* @__PURE__ */ new Set();
-	for (const match of originalXml.matchAll(STYLE_ID_PATTERN)) existing.add(match.groups["id"]);
-	const added = styles.styles.filter((style) => !existing.has(style.styleId));
+	const existing = new Set(definedStyleIds(originalXml));
+	const added = [];
+	for (const style of styles.styles) {
+		if (existing.has(style.styleId)) continue;
+		existing.add(style.styleId);
+		added.push(style);
+	}
 	if (added.length === 0) return;
 	const patched = originalXml.slice(0, rootClose) + added.map(serializeStyle).join("") + originalXml.slice(rootClose);
 	newZip.file(file.name, patched, {
@@ -1481,28 +1505,60 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		compressionOptions: { level: compressionLevel }
 	});
 }
+/**
+* The XML to write for a patched note part, or null to keep the original.
+*
+* A refusal over comment-range balance is not a failure to serialize: the
+* splice was too narrow to keep a comment's range whole, so the part is
+* written from the model, which is balanced with itself and with the
+* `document.xml` this repack rewrites beside it. Word's required separator
+* notes come back synthesized rather than byte-exact, the price of keeping the
+* comment anchored to the text it was written about. Any other refusal means a
+* changed paragraph could not be located in the part at all, which no wider
+* rewrite fixes.
+*/
+const notePartXmlFor = ({ patch, originalXml, replacementXml, hasDirtyParagraph, elementName, partName }) => {
+	const keepOriginal = () => {
+		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${partName}`);
+		return null;
+	};
+	switch (patch.type) {
+		case "patched": return patch.xml === originalXml ? keepOriginal() : patch.xml;
+		case "refused": switch (patch.reason) {
+			case "comment-range-balance": return replacementXml;
+			case "unroutable-paragraph": return keepOriginal();
+			default: {
+				const unreachable = patch.reason;
+				return panic("Unhandled note-part patch refusal", { reason: unreachable });
+			}
+		}
+		default: return panic("Unhandled note-part patch", { patch });
+	}
+};
 async function patchNotePartIntoZip({ conventionalLowerPath, currentXml, replacementXml, baselineFrom, elementName, changedNoteParaIds, originalZip, newZip, compressionLevel }) {
 	const file = findNotePartEntry(originalZip, conventionalLowerPath);
 	if (!file) return;
 	const originalXml = await file.async("text");
 	const baselineXml = baselineFrom(originalXml);
 	const effectiveChangedNoteParaIds = changedNoteParaIds ?? collectChangedNoteParaIds(baselineXml, currentXml);
-	const patched = buildPatchedNotePartXml({
+	const currentParaIds = collectParaIds(currentXml);
+	const patchedXml = notePartXmlFor({
+		patch: buildPatchedNotePartXml({
+			originalXml,
+			baselineXml,
+			serializedXml: currentXml,
+			replacementXml,
+			elementName,
+			changedParaIds: effectiveChangedNoteParaIds
+		}),
 		originalXml,
-		baselineXml,
-		serializedXml: currentXml,
 		replacementXml,
+		hasDirtyParagraph: [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId)),
 		elementName,
-		changedParaIds: effectiveChangedNoteParaIds
+		partName: file.name
 	});
-	const currentParaIds = collectParaIds(currentXml);
-	const hasDirtyParagraph = [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId));
-	if (patched === null || hasDirtyParagraph && patched === originalXml) {
-		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${file.name}`);
-		return;
-	}
-	if (patched === originalXml) return;
-	newZip.file(file.name, patched, {
+	if (patchedXml === null || patchedXml === originalXml) return;
+	newZip.file(file.name, patchedXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});

package/dist/docx/runParser.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/runParser.d.ts
 /**
  * `w:vertAlign` `baseline` is the reserved value that means "no vertical

package/dist/docx/runParser.js

@@ -1,9 +1,12 @@
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseDiagramPreview } from "./diagramPreview.js";
+import { parseFieldState } from "./fieldState.js";
 import { isGroupDrawing, parseGroupDrawing } from "./groupDrawingParser.js";
 import { parseImage } from "./imageParser.js";
 import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { preserveRunChild } from "./preservedRunContent.js";
 import { parseShading } from "./shadingParser.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
@@ -11,7 +14,7 @@ import { resolveThemeFontRef } from "./themeParser.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { parseVmlImageContent, shouldPreserveRawVmlPict } from "./vmlImageParser.js";
-import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, selectAlternateContentBranch } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
@@ -419,17 +422,14 @@ function parseEndnoteReference(element) {
 */
 function parseFieldChar(element) {
 	const fldCharType = getAttribute(element, "w", "fldCharType");
-	const fldLock = parseOnOffAttribute(element, "w", "fldLock") === true;
-	const dirty = parseOnOffAttribute(element, "w", "dirty") === true;
 	let charType = "begin";
 	if (fldCharType === "separate") charType = "separate";
 	else if (fldCharType === "end") charType = "end";
 	const content = {
 		type: "fieldChar",
-		charType
+		charType,
+		...parseFieldState(element)
 	};
-	if (fldLock) content.fldLock = true;
-	if (dirty) content.dirty = true;
 	const numberingChange = findChild(element, "w", "numberingChange");
 	if (numberingChange) {
 		const original = getAttribute(numberingChange, "w", "original");
@@ -576,10 +576,11 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 		}
 		case "object": {
 			const objectPreview = parseVmlImageContent(child, rels, media, rootXmlns);
-			if (objectPreview) contents.push(objectPreview);
+			contents.push(objectPreview ?? preserveRunChild(child));
 			break;
 		}
 		case "rPr": break;
+		case "commentReference": break;
 		case "lastRenderedPageBreak":
 			contents.push({ type: "renderedPageBreak" });
 			break;
@@ -637,11 +638,9 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 			if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
 			break;
 		}
-		case "footnoteRef":
-		case "endnoteRef": break;
-		case "separator":
-		case "continuationSeparator": break;
-		default: break;
+		default:
+			contents.push(preserveRunChild(child));
+			break;
 	}
 	return contents;
 }
@@ -668,6 +667,11 @@ function parseRun(node, styles, theme, rels = null, media = null, rootXmlns = {}
 		if (propertyChangesResult) run.propertyChanges = propertyChangesResult;
 	}
 	run.content = parseRunContents(node, rels, media, mergeXmlnsDeclarations(rootXmlns, node));
+	const remainder = attributeRemainder({
+		element: node,
+		modelled: NO_MODELLED_ATTRIBUTES
+	});
+	if (remainder) run.preservedAttributes = remainder;
 	return run;
 }
 /**

package/dist/docx/sectionParser.js

@@ -1,3 +1,4 @@
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseBorderSpec } from "./borderParser.js";
 import { parseFooterReference, parseHeaderReference } from "./headerFooterRefParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
@@ -159,7 +160,8 @@ function parseSectionProperties(sectPr, context) {
 		if (space !== void 0) props.columnSpace = space;
 		const equalWidth = parseOnOffAttribute(cols, "w", "equalWidth");
 		if (equalWidth !== void 0) props.equalWidth = equalWidth;
-		if (parseOnOffAttribute(cols, "w", "sep") === true) props.separator = true;
+		const separator = parseOnOffAttribute(cols, "w", "sep");
+		if (separator !== void 0) props.separator = separator;
 		const colElements = findChildren(cols, "w", "col");
 		if (colElements.length > 0) {
 			props.columns = [];
@@ -310,6 +312,11 @@ function parseSectionProperties(sectPr, context) {
 		return change;
 	});
 	if (propertyChanges.length > 0) props.propertyChanges = propertyChanges;
+	const remainder = attributeRemainder({
+		element: sectPr,
+		modelled: NO_MODELLED_ATTRIBUTES
+	});
+	if (remainder) props.preservedAttributes = remainder;
 	Object.defineProperty(props, unserializedSectionPropertyChildNames, {
 		enumerable: true,
 		value: unhandledChildNames

package/dist/docx/selectiveXmlPatch.d.ts

@@ -109,6 +109,24 @@ declare function buildPatchedDocumentXml(originalXml: string, serializedXml: str
  * the caller can fall back to preserving the original part verbatim.
  */
 declare function buildPatchedNoteXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+/** One region of a part replaced by re-serialized XML. */
+type XmlSplice = {
+  start: number;
+  end: number;
+  newXml: string;
+};
+/**
+ * Apply `splices` to `xml`, end-to-start so earlier offsets stay valid.
+ *
+ * Every selective patch is a splice, and every splice goes through here, so
+ * the refusal below is a property of the operation rather than a check each
+ * site has to remember. A patch rewrites the regions an edit touched and keeps
+ * the rest of the part byte-for-byte, so it can write half a comment range:
+ * invalid OOXML that anchors the comment to nothing. Answers null when it
+ * would, leaving the caller to rewrite a wider region — ultimately the whole
+ * part from the model, which is balanced with itself.
+ */
+declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
 type NoteElementName = "footnote" | "endnote";
 declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
 type BuildPatchedNotePartXmlOptions = {
@@ -119,6 +137,25 @@ type BuildPatchedNotePartXmlOptions = {
   elementName: NoteElementName;
   changedParaIds?: ReadonlySet<string>;
 };
+/** Why a note part could not be patched; see {@link NotePartPatch}. */
+type NotePartPatchRefusal =
+/** A note element, or a changed paragraph, was missing or ambiguous. */
+"unroutable-paragraph" |
+/** Even rewriting whole notes would leave a comment range with one half. */
+"comment-range-balance";
+/**
+ * What patching a note part produced. `refused` is not a failure to serialize:
+ * the caller writes the part from the model instead, the note-part reading of
+ * the fall back to a full repack the document story takes when its own splice
+ * is refused.
+ */
+type NotePartPatch = {
+  type: "patched";
+  xml: string;
+} | {
+  type: "refused";
+  reason: NotePartPatchRefusal;
+};
 /**
  * Patch an existing note part from its model serialization.
  *
@@ -130,8 +167,15 @@ type BuildPatchedNotePartXmlOptions = {
  * notes, and unaffected equal-shape paragraphs remain byte-exact.
  * `replacementXml` also supplies synthesized automatic note-reference marks,
  * which the parsed model intentionally omits.
+ *
+ * A comment can be anchored on a note's own text, so its range spans that
+ * note's paragraphs and an edit inside the span moves a range half from one
+ * paragraph to another. Replacing only the dirty paragraph then drops the half
+ * it held and leaves the other standing, so {@link spliceXml} refuses the
+ * result and the changed notes are rewritten whole instead — model content on
+ * both sides of the range, with every other note still byte-exact.
  */
-declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): string | null;
+declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): NotePartPatch;
 type ChangedNumberingDefs = {
   abstractNums: Set<string>;
   nums: Set<string>;
@@ -178,4 +222,4 @@ declare const patchNumberingDefinitions: ({ originalXml, baselineXml, currentXml
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, validatePatchSafety };
+export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, spliceXml, validatePatchSafety };