@stll/folio-core 0.45.0 → 0.46.0

package/dist/docx/commentParser.js

@@ -1,8 +1,10 @@
 import { commentThreadParaId } from "./commentThreadKey.js";
+import { CAPTURE, dispatchChildren } from "./containerChildren.js";
+import { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute } from "./paraIdAttribute.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 import { parseRunProperties } from "./runParser.js";
-import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
+import { findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentParser.ts
 /**
@@ -26,26 +28,6 @@ import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 /** The whole lexical form of `ST_DecimalNumber`: an optional sign and digits. */
 const DECIMAL_NUMBER = /^[+-]?\d+$/u;
 const DEFAULT_ANNOTATION_REFERENCE_STYLE_ID = "CommentReference";
-/**
-* The namespaces a paraId may be written in: Word 2010 and Word 2012 wordml.
-*
-* Resolved by URI rather than by prefix, because the value is a thread key: an
-* unrelated `vendor:paraId` picked up by local name alone would key a comment
-* to the wrong thread and carry that thread's date, parent and resolved state.
-*/
-const PARA_ID_NAMESPACE_URIS = /* @__PURE__ */ new Set([NAMESPACES.w14, NAMESPACES.w15]);
-/**
-* A paraId join key, wherever an exporter writes it: on `w:comment` or `w:p`.
-*
-* One reading for both, so the wrapper and the paragraphs cannot come to
-* disagree about what counts as a key. The literal reads are the fallback for
-* a part that writes a conventional prefix without binding it, which no URI
-* lookup can resolve.
-*/
-const paraIdAttribute = (element) => {
-	const raw = getAttributeByNamespaceUri(element, PARA_ID_NAMESPACE_URIS, "paraId") ?? element.attributes?.["w14:paraId"] ?? element.attributes?.["w15:paraId"] ?? getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "paraId") ?? element.attributes?.["w:paraId"];
-	return raw === null || raw === void 0 ? void 0 : String(raw);
-};
 const normalizeAnnotationReferenceFormatting = (formatting) => {
 	if (formatting?.styleId === DEFAULT_ANNOTATION_REFERENCE_STYLE_ID && Object.keys(formatting).length === 1) return;
 	return formatting;
@@ -57,7 +39,7 @@ const normalizeFirstCommentParagraph = (paragraphElement, paragraph, theme) => {
 	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme) : void 0);
 	const firstParsedContent = paragraph.content.at(0);
 	return {
-		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.length === 0 ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
+		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.every((item) => item.type === "preservedXml" && item.text === "") ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
 		...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {}
 	};
 };
@@ -75,9 +57,9 @@ function parseCommentsExtensible(xml) {
 	const container = findChild(root, "w16cex", "commentsExtensible") ?? root;
 	for (const child of getChildElements(container)) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "comment") continue;
-		const paraId = getAttribute(child, "w16cex", "paraId") ?? getAttribute(child, "w15", "paraId") ?? child.attributes?.["w16cex:paraId"] ?? child.attributes?.["w15:paraId"];
-		const dateUtc = getAttribute(child, "w16cex", "dateUtc") ?? getAttribute(child, "w15", "dateUtc") ?? child.attributes?.["w16cex:dateUtc"] ?? child.attributes?.["w15:dateUtc"];
-		const key = paraId === null || paraId === void 0 ? null : String(paraId).toUpperCase();
+		const paraId = paraIdAttribute(child);
+		const dateUtc = getAttributeByNamespaceUri(child, PARA_ID_NAMESPACE_URIS, "dateUtc") ?? child.attributes?.["w16cex:dateUtc"] ?? child.attributes?.["w15:dateUtc"];
+		const key = paraId === void 0 ? null : paraId.toUpperCase();
 		if (key && dateUtc && !dateUtcByParaId.has(key)) dateUtcByParaId.set(key, String(dateUtc));
 	}
 	return dateUtcByParaId;
@@ -102,11 +84,11 @@ function parseCommentsExtended(xml) {
 	const container = findChild(root, "w15", "commentsEx") ?? root;
 	for (const child of getChildElements(container)) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "commentEx") continue;
-		const paraId = getAttribute(child, "w15", "paraId") ?? child.attributes?.["w15:paraId"];
+		const paraId = paraIdAttribute(child);
 		if (!paraId) continue;
-		const key = String(paraId).toUpperCase();
+		const key = paraId.toUpperCase();
 		if (infoByParaId.has(key)) continue;
-		const parentParaId = getAttribute(child, "w15", "paraIdParent") ?? child.attributes?.["w15:paraIdParent"];
+		const parentParaId = paraIdParentAttribute(child);
 		const doneAttr = getAttribute(child, "w15", "done") ?? child.attributes?.["w15:done"];
 		const info = {};
 		if (parentParaId) info.parentParaId = String(parentParaId).toUpperCase();
@@ -155,16 +137,50 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const done = (paraId ? extendedByParaId.get(paraId) : void 0)?.done;
 		const paragraphs = [];
 		let annotationReferenceFormatting;
-		for (const contentChild of getChildElements(child)) if ((contentChild.name?.replace(/^.*:/u, "") ?? "") === "p") {
-			const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
-			if (paragraphs.length > 0) {
-				paragraphs.push(paragraph);
-				continue;
+		const preserved = dispatchChildren({
+			element: child,
+			container: "w:comment",
+			modelledCount: () => paragraphs.length,
+			handlers: {
+				p: (contentChild) => {
+					const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
+					if (paragraphs.length > 0) {
+						paragraphs.push(paragraph);
+						return;
+					}
+					const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
+					annotationReferenceFormatting = normalized.annotationReferenceFormatting;
+					paragraphs.push(normalized.paragraph);
+				},
+				altChunk: CAPTURE,
+				bookmarkEnd: CAPTURE,
+				bookmarkStart: CAPTURE,
+				commentRangeEnd: CAPTURE,
+				commentRangeStart: CAPTURE,
+				customXml: CAPTURE,
+				customXmlDelRangeEnd: CAPTURE,
+				customXmlDelRangeStart: CAPTURE,
+				customXmlInsRangeEnd: CAPTURE,
+				customXmlInsRangeStart: CAPTURE,
+				customXmlMoveFromRangeEnd: CAPTURE,
+				customXmlMoveFromRangeStart: CAPTURE,
+				customXmlMoveToRangeEnd: CAPTURE,
+				customXmlMoveToRangeStart: CAPTURE,
+				del: CAPTURE,
+				ins: CAPTURE,
+				moveFrom: CAPTURE,
+				moveFromRangeEnd: CAPTURE,
+				moveFromRangeStart: CAPTURE,
+				moveTo: CAPTURE,
+				moveToRangeEnd: CAPTURE,
+				moveToRangeStart: CAPTURE,
+				permEnd: CAPTURE,
+				permStart: CAPTURE,
+				proofErr: CAPTURE,
+				sdt: CAPTURE,
+				tbl: CAPTURE
 			}
-			const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
-			annotationReferenceFormatting = normalized.annotationReferenceFormatting;
-			paragraphs.push(normalized.paragraph);
-		}
+		});
 		if (paraId && !commentIdByParaId.has(paraId)) commentIdByParaId.set(paraId, id);
 		parsed.push({
 			comment: {
@@ -174,6 +190,7 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 				...date !== void 0 ? { date } : {},
 				...done !== void 0 ? { done } : {},
 				...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {},
+				...preserved !== void 0 ? { preserved } : {},
 				content: paragraphs
 			},
 			threadParaId: paraId

package/dist/docx/commentRangeIntegrity.d.ts

@@ -1,5 +1,20 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/commentRangeIntegrity.d.ts
+/**
+ * Comment ids whose range is not a start followed by an end in this story's
+ * XML. Either half alone is invalid OOXML and anchors nothing: Word shows no
+ * comment for a range that never opens.
+ */
+declare const unbalancedCommentRangeIds: (xml: string) => Set<string>;
+/**
+ * Whether rewriting `originalXml` into `patchedXml` left a comment range with
+ * only one half. A save patches the paragraphs an edit touched and keeps the
+ * rest of the part byte-for-byte, so an edit that moves a range's only start
+ * out of a patched paragraph and into an untouched one writes an end with no
+ * start. Ranges the source already had unbalanced are not this save's doing
+ * and stay tolerated.
+ */
+declare const patchBreaksCommentRangeBalance: (originalXml: string, patchedXml: string) => boolean;
 declare const withoutOrphanCommentRanges: (doc: document_d_exports.Document) => document_d_exports.Document;
 //#endregion
-export { withoutOrphanCommentRanges };
+export { patchBreaksCommentRangeBalance, unbalancedCommentRangeIds, withoutOrphanCommentRanges };

package/dist/docx/commentRangeIntegrity.js

@@ -1,5 +1,45 @@
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 //#region src/docx/commentRangeIntegrity.ts
+const COMMENT_RANGE_MARKER_PATTERN = /<w:commentRange(Start|End)\s[^>]*w:id="(\d+)"/gu;
+/**
+* Comment ids whose range is not a start followed by an end in this story's
+* XML. Either half alone is invalid OOXML and anchors nothing: Word shows no
+* comment for a range that never opens.
+*/
+const unbalancedCommentRangeIds = (xml) => {
+	const firstStart = /* @__PURE__ */ new Map();
+	const lastEnd = /* @__PURE__ */ new Map();
+	for (const match of xml.matchAll(COMMENT_RANGE_MARKER_PATTERN)) {
+		const [, half, id] = match;
+		if (id === void 0) continue;
+		if (half === "Start") {
+			if (!firstStart.has(id)) firstStart.set(id, match.index);
+			continue;
+		}
+		lastEnd.set(id, match.index);
+	}
+	const unbalanced = /* @__PURE__ */ new Set();
+	for (const id of /* @__PURE__ */ new Set([...firstStart.keys(), ...lastEnd.keys()])) {
+		const start = firstStart.get(id);
+		const end = lastEnd.get(id);
+		if (start === void 0 || end === void 0 || end < start) unbalanced.add(id);
+	}
+	return unbalanced;
+};
+/**
+* Whether rewriting `originalXml` into `patchedXml` left a comment range with
+* only one half. A save patches the paragraphs an edit touched and keeps the
+* rest of the part byte-for-byte, so an edit that moves a range's only start
+* out of a patched paragraph and into an untouched one writes an end with no
+* start. Ranges the source already had unbalanced are not this save's doing
+* and stay tolerated.
+*/
+const patchBreaksCommentRangeBalance = (originalXml, patchedXml) => {
+	const introduced = unbalancedCommentRangeIds(patchedXml);
+	if (introduced.size === 0) return false;
+	const preexisting = unbalancedCommentRangeIds(originalXml);
+	return [...introduced].some((id) => !preexisting.has(id));
+};
 const withoutOrphanCommentRanges = (doc) => {
 	const validCommentIds = new Set((doc.package.document.comments ?? []).map((comment) => comment.id));
 	const document = withoutOrphanDocumentBodyMarkers(doc.package.document, validCommentIds);
@@ -107,6 +147,7 @@ const withoutOrphanBlockMarkers = (blocks, validCommentIds) => {
 const withoutOrphanBlockMarker = (block, validCommentIds) => {
 	if (block.type === "paragraph") return withoutOrphanParagraphMarkers(block, validCommentIds);
 	if (block.type === "table") return withoutOrphanTableMarkers(block, validCommentIds);
+	if (block.type === "preservedBlock") return block;
 	const content = withoutOrphanBlockMarkers(block.content, validCommentIds);
 	if (!content) return block;
 	return {
@@ -180,4 +221,4 @@ const withoutOrphanParagraphMarkers = (paragraph, validCommentIds) => {
 };
 const isCommentMarker = (content) => content.type === "commentRangeStart" || content.type === "commentRangeEnd" || content.type === "commentReference";
 //#endregion
-export { withoutOrphanCommentRanges };
+export { patchBreaksCommentRangeBalance, unbalancedCommentRangeIds, withoutOrphanCommentRanges };

package/dist/docx/commentRangeJoin.d.ts

@@ -0,0 +1,9 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/commentRangeJoin.d.ts
+/**
+ * Collapse each comment's range markers to its first start and its last end.
+ * Answers how many markers were dropped.
+ */
+declare const joinCommentRangesAcrossParagraphs: (blocks: readonly document_d_exports.BlockContent[]) => number;
+//#endregion
+export { joinCommentRangesAcrossParagraphs };

package/dist/docx/commentRangeJoin.js

@@ -0,0 +1,33 @@
+import { visitCommentMarkers } from "./commentAnchorIndex.js";
+import { InlineContentRemovals } from "./paragraphTraversal.js";
+//#region src/docx/commentRangeJoin.ts
+/**
+* Collapse each comment's range markers to its first start and its last end.
+* Answers how many markers were dropped.
+*/
+const joinCommentRangesAcrossParagraphs = (blocks) => {
+	const startsById = /* @__PURE__ */ new Map();
+	const endsById = /* @__PURE__ */ new Map();
+	visitCommentMarkers(blocks, ({ content, index, item }) => {
+		if (item.type === "commentReference") return;
+		const slotsById = item.type === "commentRangeStart" ? startsById : endsById;
+		const slots = slotsById.get(item.id);
+		if (slots) {
+			slots.push({
+				content,
+				index
+			});
+			return;
+		}
+		slotsById.set(item.id, [{
+			content,
+			index
+		}]);
+	});
+	const removals = new InlineContentRemovals();
+	for (const slots of startsById.values()) for (const slot of slots.slice(1)) removals.mark(slot);
+	for (const slots of endsById.values()) for (const slot of slots.slice(0, -1)) removals.mark(slot);
+	return removals.apply();
+};
+//#endregion
+export { joinCommentRangesAcrossParagraphs };

package/dist/docx/commentReferenceCompletion.d.ts

@@ -0,0 +1,9 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/commentReferenceCompletion.d.ts
+/**
+ * Give every comment that a `commentRangeEnd` closes but no `commentReference`
+ * names a reference after its last end. Answers how many were added.
+ */
+declare const completeCommentReferences: (blocks: readonly document_d_exports.BlockContent[]) => number;
+//#endregion
+export { completeCommentReferences };

package/dist/docx/commentReferenceCompletion.js

@@ -0,0 +1,47 @@
+import { visitCommentMarkers } from "./commentAnchorIndex.js";
+//#region src/docx/commentReferenceCompletion.ts
+/**
+* Give every comment that a `commentRangeEnd` closes but no `commentReference`
+* names a reference after its last end. Answers how many were added.
+*/
+const completeCommentReferences = (blocks) => {
+	const lastRangeEnds = /* @__PURE__ */ new Map();
+	const referencedIds = /* @__PURE__ */ new Set();
+	visitCommentMarkers(blocks, ({ content, index, item }) => {
+		if (item.type === "commentReference") {
+			referencedIds.add(item.id);
+			return;
+		}
+		if (item.type === "commentRangeEnd") lastRangeEnds.set(item.id, {
+			content,
+			index
+		});
+	});
+	const insertionsByContent = /* @__PURE__ */ new Map();
+	for (const [id, { content, index }] of lastRangeEnds) {
+		if (referencedIds.has(id)) continue;
+		const pending = insertionsByContent.get(content);
+		if (pending) {
+			pending.push({
+				index,
+				id
+			});
+			continue;
+		}
+		insertionsByContent.set(content, [{
+			index,
+			id
+		}]);
+	}
+	let added = 0;
+	for (const [content, pending] of insertionsByContent) for (const { index, id } of pending.toSorted((first, second) => second.index - first.index || second.id - first.id)) {
+		content.splice(index + 1, 0, {
+			type: "commentReference",
+			id
+		});
+		added += 1;
+	}
+	return added;
+};
+//#endregion
+export { completeCommentReferences };

package/dist/docx/commentReferenceNormalization.js

@@ -39,6 +39,7 @@ const normalizeCommentReferences = ({ documentBody, comments, headers, footers,
 			normalizeTable(block);
 			return;
 		}
+		if (block.type === "preservedBlock") return;
 		normalizeBlocks(block.content);
 	};
 	const normalizeBlocks = (blocks) => {

package/dist/docx/commentReplyMarkers.js

@@ -25,34 +25,26 @@ const eachParagraph = (blocks, visit) => {
 			for (const row of block.rows ?? []) for (const cell of row.cells ?? []) eachParagraph(cell.content ?? [], visit);
 			continue;
 		}
+		if (block.type === "preservedBlock") continue;
 		eachParagraph(block.content ?? [], visit);
 	}
 };
-const scanAnchors = (surfaces) => {
-	const rangeIds = /* @__PURE__ */ new Set();
+/** Comment ids with any anchor (a range start OR a `commentReference` run). */
+const scanAnchoredIds = (surfaces) => {
 	const anchoredIds = /* @__PURE__ */ new Set();
 	for (const group of surfaceBlockGroups(surfaces)) eachParagraph(group, (paragraph) => {
-		for (const item of paragraph.content ?? []) if (item.type === "commentRangeStart") {
-			rangeIds.add(item.id);
-			anchoredIds.add(item.id);
-		} else if (item.type === "commentReference") anchoredIds.add(item.id);
+		for (const item of paragraph.content ?? []) if (item.type === "commentRangeStart" || item.type === "commentReference") anchoredIds.add(item.id);
 	});
-	return {
-		rangeIds,
-		anchoredIds
-	};
+	return anchoredIds;
 };
 /** Replies whose parent is another comment (the threaded-discussion shape). */
 const commentParentedReplies = (comments) => {
 	const commentIds = new Set(comments.map((comment) => comment.id));
 	return comments.filter((comment) => comment.parentId !== void 0 && commentIds.has(comment.parentId));
 };
-const injectIntoParagraph = (paragraph, replyIdsByParent, parentsWithRange) => {
+const injectIntoParagraph = (paragraph, replyIdsByParent) => {
 	const content = paragraph.content ?? [];
-	if (!content.some((item) => {
-		if (item.type === "commentRangeStart" || item.type === "commentRangeEnd") return replyIdsByParent.has(item.id);
-		return item.type === "commentReference" && !parentsWithRange.has(item.id) ? replyIdsByParent.has(item.id) : false;
-	})) return 0;
+	if (!content.some((item) => (item.type === "commentRangeStart" || item.type === "commentRangeEnd" || item.type === "commentReference") && replyIdsByParent.has(item.id))) return 0;
 	const next = [];
 	let injected = 0;
 	for (const item of content) {
@@ -68,7 +60,7 @@ const injectIntoParagraph = (paragraph, replyIdsByParent, parentsWithRange) => {
 			type: "commentRangeEnd",
 			id: replyId
 		});
-		else if (item.type === "commentReference" && !parentsWithRange.has(item.id)) for (const replyId of replyIdsByParent.get(item.id) ?? []) {
+		else if (item.type === "commentReference") for (const replyId of replyIdsByParent.get(item.id) ?? []) {
 			next.push({
 				type: "commentReference",
 				id: replyId
@@ -82,7 +74,7 @@ const injectIntoParagraph = (paragraph, replyIdsByParent, parentsWithRange) => {
 const synthesizeReplyRangeMarkers = (surfaces) => {
 	const replies = commentParentedReplies(surfaces.comments);
 	if (replies.length === 0) return 0;
-	const { rangeIds, anchoredIds } = scanAnchors(surfaces);
+	const anchoredIds = scanAnchoredIds(surfaces);
 	const replyIdsByParent = /* @__PURE__ */ new Map();
 	for (const reply of replies) {
 		if (anchoredIds.has(reply.id) || reply.parentId === void 0) continue;
@@ -93,7 +85,7 @@ const synthesizeReplyRangeMarkers = (surfaces) => {
 	if (replyIdsByParent.size === 0) return 0;
 	let injected = 0;
 	const visit = (paragraph) => {
-		injected += injectIntoParagraph(paragraph, replyIdsByParent, rangeIds);
+		injected += injectIntoParagraph(paragraph, replyIdsByParent);
 	};
 	for (const group of surfaceBlockGroups(surfaces)) eachParagraph(group, visit);
 	return injected;
@@ -116,7 +108,7 @@ const hasUnsynthesizedReplyRanges = (doc) => {
 	const surfaces = surfacesFromDocument(doc);
 	const replies = commentParentedReplies(surfaces.comments);
 	if (replies.length === 0) return false;
-	const { anchoredIds } = scanAnchors(surfaces);
+	const anchoredIds = scanAnchoredIds(surfaces);
 	return replies.some((reply) => !anchoredIds.has(reply.id));
 };
 //#endregion

package/dist/docx/compatibility.js

@@ -97,6 +97,7 @@ function inspectBlocks(blocks, context) {
 			});
 			continue;
 		}
+		if (block.type === "preservedBlock") continue;
 		inspectBlocks(block.content, {
 			part: context.part,
 			path: `${blockPath}.content`,

package/dist/docx/containerChildren.d.ts

@@ -0,0 +1,111 @@
+import { XmlElement } from "./xmlParser.js";
+import { DeclaredChild, DispatchedContainer } from "./containerChildren.gen.js";
+import { PreservedMarkup } from "@stll/docx-core/model";
+//#region src/docx/containerChildren.d.ts
+/** Keep this child's markup verbatim, in place. */
+declare const CAPTURE = "capture";
+/**
+ * Another reader owns this child, and re-emits it.
+ *
+ * `w:rPr` under a run, read by `parseRunProperties`; `w:commentReference`
+ * under a run, lifted out by the paragraph parser. Capturing one of these as
+ * well would write it twice, so the disposition has to be stated rather than
+ * left to a bare `break`.
+ */
+declare const OWNED_ELSEWHERE = "owned-elsewhere";
+/**
+ * This child goes with the wrapper folio does not keep.
+ *
+ * `w:smartTagPr` is the case: folio unwraps `w:smartTag` and splices its
+ * content into the paragraph, so the properties describing the wrapper have
+ * nothing left to describe and capturing them would put a `w:smartTagPr`
+ * where the schema does not admit one. The drop is stated here and recorded
+ * in `specifications/container-contract/contract.json`, which is the whole
+ * difference between this and a `default` that says nothing.
+ */
+declare const DROPPED_WITH_ITS_WRAPPER = "dropped-with-its-wrapper";
+/** What a container does with one declared child. */
+type ChildDisposition = ((child: XmlElement) => void) | typeof CAPTURE | typeof DROPPED_WITH_ITS_WRAPPER | typeof OWNED_ELSEWHERE;
+/**
+ * A total decision per declared child.
+ *
+ * `Record`, never `Partial<Record>`: a partial map lets a new declared child
+ * land without a decision, which is the drop this module exists to prevent.
+ */
+type ChildHandlers<Container extends DispatchedContainer> = Readonly<Record<DeclaredChild<Container>, ChildDisposition>>;
+type DispatchChildrenOptions<Container extends DispatchedContainer> = {
+  /** The container element, as the source wrote it. */
+  element: XmlElement;
+  /** Which container's declared-child set the handler map must be total over. */
+  container: Container;
+  handlers: ChildHandlers<Container>;
+  /**
+   * How many modelled children the caller holds right now. Called once per
+   * captured child, so the capture lands after the siblings already read.
+   */
+  modelledCount: () => number;
+  /**
+   * Dispositions for names the container's content model does not declare.
+   *
+   * The schema declares a container's children in one namespace, so anything
+   * else is undeclared by construction — which is why the sink is the default
+   * and why this map is not part of the totality check: there is no finite set
+   * to be total over. `mc:AlternateContent` is the case that needs it. It is
+   * markup compatibility, legal wherever its fallback is, and folio models it
+   * by selecting a branch and reading that; capturing the wrapper whole would
+   * keep the bytes and lose every paragraph inside it to the editor.
+   *
+   * Each entry is a claim that folio reads this name in this container.
+   */
+  undeclared?: Readonly<Record<string, ChildDisposition>>;
+  /**
+   * Dispositions for whole namespaces the declared set does not cover, by
+   * namespace URI, consulted after {@link undeclared} and before the sink.
+   *
+   * OOXML maths is the case. `m:EG_OMathMathElements` is admitted wherever
+   * `m:oMath` is, so `<w:ins><m:f/></w:ins>` is a tracked insertion of a
+   * fraction with no `m:oMath` around it; there are two dozen such names and
+   * folio treats every one of them the same way, as markup it carries rather
+   * than a structure it models. Naming the namespace states that once. It is
+   * not a `default` in disguise: a child from any *other* namespace still goes
+   * to the sink, which is the branch a hand-written `default` gets wrong.
+   */
+  undeclaredNamespaces?: Readonly<Record<string, ChildDisposition>>;
+};
+/**
+ * The Transitional spelling of a namespace, so one disposition covers both.
+ *
+ * ISO Strict writes the same content model under its own URIs: maths is
+ * `purl.oclc.org/ooxml/officeDocument/math` rather than
+ * `schemas.openxmlformats.org/officeDocument/2006/math`. A namespace-keyed
+ * disposition written in Transitional would otherwise send a Strict
+ * document's maths to the sink, which models it as bytes instead of an
+ * equation. The pairs come from the generated table rather than a second list
+ * here, so a namespace cannot be paired in one place and forgotten in the
+ * other.
+ */
+declare const transitionalNamespaceOf: (namespace: string) => string;
+/**
+ * Walk a container's children, handing each to its handler and the rest to the
+ * sink.
+ *
+ * @returns the container's unmodelled markup, or `undefined` when it held
+ *   none — an empty record is never written, so a fully modelled container
+ *   stays byte-identical in the model.
+ */
+declare const dispatchChildren: <Container extends DispatchedContainer>({ element, handlers, modelledCount, undeclared, undeclaredNamespaces }: DispatchChildrenOptions<Container>) => PreservedMarkup | undefined;
+/**
+ * Put a container's modelled children back with its preserved ones between
+ * them, in source position.
+ *
+ * Where the content model demands schema order the caller has already put its
+ * modelled children in that order; the sink's `index` then places each capture
+ * between the same two siblings it sat between when it was read.
+ *
+ * @param wrap turns one capture's markup into whatever the caller's list holds
+ */
+declare const withPreservedChildren: <Item>(modelled: readonly Item[], preserved: PreservedMarkup | undefined, wrap: (xml: string) => Item) => Item[];
+/** {@link withPreservedChildren} for a caller that already holds markup. */
+declare const serializeWithPreservedChildren: (modelled: readonly string[], preserved: PreservedMarkup | undefined) => string;
+//#endregion
+export { CAPTURE, ChildDisposition, ChildHandlers, DROPPED_WITH_ITS_WRAPPER, OWNED_ELSEWHERE, dispatchChildren, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };

package/dist/docx/containerChildren.gen.d.ts

@@ -0,0 +1,28 @@
+//#region src/docx/containerChildren.gen.d.ts
+/**
+ * GENERATED FILE — do not edit.
+ *
+ * Every child the Transitional content model declares for a container folio
+ * dispatches, derived from the committed schema graph by
+ * `scripts/generate-container-children.ts`. The shared child dispatcher makes
+ * a handler map total over these names, so a container cannot gain a declared
+ * child without somebody deciding whether it is modelled or captured.
+ * Regenerate with:
+ *
+ *   bun run generate:container-children
+ */
+declare const CONTAINER_CHILDREN: {
+  readonly "w:comment": readonly ["altChunk", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "p", "permEnd", "permStart", "proofErr", "sdt", "tbl"];
+  readonly "run-level-content": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "pPr", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "smartTagPr", "subDoc"];
+  readonly "table-content": readonly ["bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "customXmlPr", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "sdt", "tblGrid", "tblPr", "tr"];
+  readonly "row-content": readonly ["bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "sdt", "tblPrEx", "tc", "tr", "trPr"];
+  readonly "w:hyperlink": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "subDoc"];
+  readonly "w:fldSimple": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldData", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "subDoc"];
+  readonly "block-content": readonly ["altChunk", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "p", "permEnd", "permStart", "proofErr", "sdt", "sectPr", "tbl", "tcPr"];
+};
+/** A container the shared child dispatcher covers. */
+type DispatchedContainer = keyof typeof CONTAINER_CHILDREN;
+/** Every child name the schema declares for `Container`. */
+type DeclaredChild<Container extends DispatchedContainer> = (typeof CONTAINER_CHILDREN)[Container][number];
+//#endregion
+export { CONTAINER_CHILDREN, DeclaredChild, DispatchedContainer };