@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/server/migrateYjsAttrSchema.js

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

package/dist/docx/server/validateDocxConformance.js

@@ -3,6 +3,7 @@ import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "../encryption/con
 import { DocxModelValidationError, validateFolioDocumentModel } from "../modelValidation.js";
 import { DocxParseError, parseDocx } from "../parser.js";
 import { findChildByLocalName, getAttributeAnyPrefix, getLocalName, getNamespacePrefix, parseXmlDocument } from "../xmlParser.js";
+import { XmlResourceLimitError } from "../xmlResourceLimits.js";
 import { getDocxXmlSafetyIssue } from "../xmlSafety.js";
 import { DocxArchiveError, loadDocxArchive } from "./boundedArchive.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
@@ -112,11 +113,31 @@ const XML_SAFETY_ISSUE = {
 		message: "An XML package part is not well formed."
 	}
 };
+/**
+* Read a part for inspection, including one the safe reader declines.
+*
+* `readEntryString` runs the XML structure preflight, and the preflight
+* refuses to scan markup it cannot count — a document type declaration, an
+* unterminated tag — which is exactly the markup this check exists to report.
+* Such a part is read raw and classified below, so the report names why the
+* package is invalid instead of saying it could not tell. A part that overran
+* a real bound still refuses, and the caller reports that as indeterminate,
+* because a package too large to scan is not a package known to be wrong.
+*/
+const readPartForInspection = async (archive, part) => {
+	try {
+		return await archive.readEntryString(part);
+	} catch (error) {
+		if (!(error instanceof XmlResourceLimitError) || error.limit !== "syntax") throw error;
+		const bytes = await archive.readEntryUint8(part);
+		return bytes === null ? null : new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+	}
+};
 const validateXmlParts = async (archive, report) => {
 	const xmlByPath = /* @__PURE__ */ new Map();
 	let hasInvalidXml = false;
 	for (const part of archive.entries.filter((path) => XML_PART_PATTERN.test(path)).toSorted()) {
-		const xml = await archive.readEntryString(part);
+		const xml = await readPartForInspection(archive, part);
 		if (xml === null) continue;
 		xmlByPath.set(part, xml);
 		const safetyIssue = getDocxXmlSafetyIssue(xml);

package/dist/docx/shapeParser.js

@@ -1,4 +1,5 @@
 import { parseAnchorPosition, parseAnchorWrap, parseFill, parseOutline } from "./drawingUtils.js";
+import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.js";
 import { ShapeTypeSchema, narrowEnum } from "./parserEnums.js";
 import { findAllDeep, findChildByLocalName, findChildren, getAttribute, getChildElements, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/shapeParser.ts
@@ -26,13 +27,13 @@ function parseTransform(xfrm) {
 		height: parseNumericAttribute(ext, null, "cy") ?? 0
 	};
 	const rotation = rotToDegrees(getAttribute(xfrm, null, "rot"));
-	const flipH = parseOnOffAttribute(xfrm, null, "flipH") === true;
-	const flipV = parseOnOffAttribute(xfrm, null, "flipV") === true;
-	if (rotation === void 0 && !flipH && !flipV) return { size };
+	const flipH = parseOnOffAttribute(xfrm, null, "flipH");
+	const flipV = parseOnOffAttribute(xfrm, null, "flipV");
+	if (rotation === void 0 && flipH === void 0 && flipV === void 0) return { size };
 	const transform = {};
 	if (rotation !== void 0) transform.rotation = rotation;
-	if (flipH) transform.flipH = true;
-	if (flipV) transform.flipV = true;
+	if (flipH !== void 0) transform.flipH = flipH;
+	if (flipV !== void 0) transform.flipV = flipV;
 	return {
 		size,
 		transform
@@ -139,16 +140,15 @@ function parseShape(node) {
 	const fill = parseShapeFill(spPr);
 	const outline = parseOutline(spPr);
 	const id = cNvPr ? getAttribute(cNvPr, null, "id") ?? void 0 : void 0;
-	const name = cNvPr ? getAttribute(cNvPr, null, "name") ?? void 0 : void 0;
 	const shape = {
 		type: "shape",
 		shapeType,
-		size
+		size,
+		...parseNonVisualDrawingNames(cNvPr)
 	};
 	const geometryAdjustments = parseGeometryAdjustments(spPr);
 	if (geometryAdjustments !== void 0) shape.geometryAdjustments = geometryAdjustments;
 	if (id !== void 0) shape.id = id;
-	if (name !== void 0) shape.name = name;
 	if (fill !== void 0) shape.fill = fill;
 	if (outline !== void 0) shape.outline = outline;
 	if (transform !== void 0) shape.transform = transform;
@@ -193,9 +193,11 @@ function parseShapeFromDrawing(drawingEl) {
 	const docPr = findChildByLocalName(container, "docPr");
 	if (docPr) {
 		const id = getAttribute(docPr, null, "id");
-		const name = getAttribute(docPr, null, "name");
 		if (id !== null) shape.id = id;
-		if (name !== null) shape.name = name;
+		const names = parseNonVisualDrawingNames(docPr);
+		if (names.name !== void 0) shape.name = names.name;
+		if (names.alt !== void 0) shape.alt = names.alt;
+		if (names.title !== void 0) shape.title = names.title;
 	}
 	return shape;
 }

package/dist/docx/tableParser.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";
 //#region src/docx/tableParser.d.ts
 /**
  * Sanity cap on `w:gridSpan` (and the derived table column count). Word's

package/dist/docx/tableParser.js

@@ -1,7 +1,8 @@
-import { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker } from "./blockRangeMarkers.js";
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { appendBookmarkMarkerToLastParagraphInBlocks, appendBookmarkMarkerToLastParagraphInCells, prependBookmarkMarkersToFirstParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInCell } from "./bookmarkPlacement.js";
 import { parseBorderSpec } from "./borderParser.js";
+import { CAPTURE, OWNED_ELSEWHERE, dispatchChildren, withPreservedChildren } from "./containerChildren.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { FloatingTableXSpecSchema, FloatingTableYSpecSchema, TableCellTextDirectionSchema, narrowEnum } from "./parserEnums.js";
@@ -10,7 +11,7 @@ import { TABLE_LOOK_FLAGS } from "./tableLook.js";
 import { parsePropertyChangeInfo, parseTrackedChangeInfo } from "./trackedChangeInfo.js";
 import { percentageSpelling, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { cloneElement, findChild, findChildByLocalName, findChildren, getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, parseTableMeasurementValue, selectAlternateContentBranch } from "./xmlParser.js";
+import { cloneElement, findChild, findChildByLocalName, findChildren, getAttribute, getLocalName, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, parseTableMeasurementValue, selectAlternateContentBranch } from "./xmlParser.js";
 //#region src/docx/tableParser.ts
 /**
 * Sanity cap on `w:gridSpan` (and the derived table column count). Word's
@@ -472,59 +473,87 @@ function withContainerXmlns(options, element) {
 	};
 }
 function parseCellContent(tcElement, styles, theme, numbering, rels, media, options) {
-	const content = [];
+	const modelled = [];
 	const pendingBookmarkMarkers = [];
-	const pendingRangeMarkers = [];
-	const elements = getChildElements(tcElement);
-	const parseCellChild = (child, childOptions = options) => {
-		if (!child.name) return;
-		const localName = getLocalName(child.name);
-		if (localName === "p") {
-			const para = parseParagraph(child, styles, theme, numbering, rels, media, childOptions);
-			enrichParagraphTextBoxes(para, child, styles, theme, numbering, rels, media, parseTable);
-			prependPendingBookmarkMarkers(para, pendingBookmarkMarkers);
-			attachPendingRangeMarkers(para, pendingRangeMarkers);
-			content.push(para);
-			return;
-		}
-		if (localName === "tbl") {
-			const table = parseTable(child, styles, theme, numbering, rels, media, childOptions);
-			if (!table) return;
-			if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-			attachPendingRangeMarkers(table, pendingRangeMarkers);
-			content.push(table);
-			return;
-		}
-		if (localName === "AlternateContent") {
-			const selectedBranch = selectAlternateContentBranch(child);
-			if (!selectedBranch) return;
-			const branchOptions = withContainerXmlns(withContainerXmlns(childOptions, child), selectedBranch);
-			for (const selectedChild of getChildElements(selectedBranch)) parseCellChild(selectedChild, branchOptions);
-			return;
-		}
-		if (localName === "sdt") {
-			const sdtContent = findChildByLocalName(child, "sdtContent");
-			if (!sdtContent) return;
-			const sdtContentOptions = withContainerXmlns(withContainerXmlns(childOptions, child), sdtContent);
-			for (const sdtChild of getChildElements(sdtContent)) parseCellChild(sdtChild, sdtContentOptions);
-			return;
-		}
-		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
-			const marker = parseBookmarkMarker(child, localName);
-			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);
-			return;
-		}
-		if (isBlockRangeMarker(localName)) pendingRangeMarkers.push(captureVerbatimXml(child));
+	const captured = [];
+	const dispatchCellChildren = (element, childOptions) => {
+		const preserved = dispatchChildren({
+			element,
+			container: "block-content",
+			modelledCount: () => modelled.length,
+			undeclared: { AlternateContent: (child) => {
+				const selectedBranch = selectAlternateContentBranch(child);
+				if (!selectedBranch) return;
+				dispatchCellChildren(selectedBranch, withContainerXmlns(withContainerXmlns(childOptions, child), selectedBranch));
+			} },
+			handlers: {
+				p: (child) => {
+					const para = parseParagraph(child, styles, theme, numbering, rels, media, childOptions);
+					enrichParagraphTextBoxes(para, child, styles, theme, numbering, rels, media, parseTable);
+					prependPendingBookmarkMarkers(para, pendingBookmarkMarkers);
+					modelled.push(para);
+				},
+				tbl: (child) => {
+					const table = parseTable(child, styles, theme, numbering, rels, media, childOptions);
+					if (!table) return;
+					if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
+					modelled.push(table);
+				},
+				sdt: (child) => {
+					const sdtContent = findChildByLocalName(child, "sdtContent");
+					if (!sdtContent) return;
+					dispatchCellChildren(sdtContent, withContainerXmlns(withContainerXmlns(childOptions, child), sdtContent));
+				},
+				bookmarkStart: (child) => {
+					collectCellBookmarkMarker(child, "bookmarkStart", modelled, pendingBookmarkMarkers);
+				},
+				bookmarkEnd: (child) => {
+					collectCellBookmarkMarker(child, "bookmarkEnd", modelled, pendingBookmarkMarkers);
+				},
+				tcPr: OWNED_ELSEWHERE,
+				sectPr: CAPTURE,
+				altChunk: 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
+			}
+		});
+		if (preserved?.children) captured.push(...preserved.children);
 	};
-	for (const child of elements) parseCellChild(child);
-	if (content.length === 0) content.push({
+	dispatchCellChildren(tcElement, options);
+	if (modelled.length === 0) modelled.push({
 		type: "paragraph",
 		content: [...pendingBookmarkMarkers]
 	});
-	else if (pendingBookmarkMarkers.length > 0) appendBookmarkMarkersToLastParagraphInBlocks(content, pendingBookmarkMarkers);
-	attachTrailingRangeMarkers(content, pendingRangeMarkers);
-	return content;
-}
+	else if (pendingBookmarkMarkers.length > 0) appendBookmarkMarkersToLastParagraphInBlocks(modelled, pendingBookmarkMarkers);
+	return withPreservedChildren(modelled, { children: captured }, (xml) => ({
+		type: "preservedBlock",
+		xml
+	}));
+}
+const collectCellBookmarkMarker = (child, localName, content, pending) => {
+	const marker = parseBookmarkMarker(child, localName);
+	if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pending.push(marker);
+};
 /**
 * Parse a table cell (w:tc)
 *
@@ -576,29 +605,79 @@ function parseTableRow(trElement, styles, theme, numbering, rels, media, options
 	if (rowStructChange !== void 0) row.structuralChange = rowStructChange;
 	const rowOptions = withContainerXmlns(options, trElement);
 	const pendingBookmarkMarkers = [];
-	const parseRowChild = (child, childOptions = rowOptions) => {
-		const localName = getLocalName(child.name);
-		if (localName === "tc") {
-			const cell = parseTableCell(child, styles, theme, numbering, rels, media, childOptions);
-			if (pendingBookmarkMarkers.length > 0) {
-				prependBookmarkMarkersToFirstParagraphInCell(cell, pendingBookmarkMarkers);
-				pendingBookmarkMarkers.length = 0;
+	const preservedChildren = [];
+	/**
+	* One row's children, or a row-level content control's.
+	*
+	* folio unwraps `w:sdt` here and splices its rows' content into the row, so
+	* the recursion walks the control's content with the same map; the sink is
+	* the row's either way, because the control keeps no wrapper to hold one.
+	*/
+	const dispatchRowChildren = (element, childOptions) => {
+		const captured = dispatchChildren({
+			element,
+			container: "row-content",
+			modelledCount: () => row.cells.length,
+			handlers: {
+				tc: (child) => {
+					const cell = parseTableCell(child, styles, theme, numbering, rels, media, childOptions);
+					if (pendingBookmarkMarkers.length > 0) {
+						prependBookmarkMarkersToFirstParagraphInCell(cell, pendingBookmarkMarkers);
+						pendingBookmarkMarkers.length = 0;
+					}
+					row.cells.push(cell);
+				},
+				sdt: (child) => {
+					const sdtContent = findChildByLocalName(child, "sdtContent");
+					if (!sdtContent) return;
+					const sdtOptions = withContainerXmlns(childOptions, child);
+					dispatchRowChildren(sdtContent, withContainerXmlns(sdtOptions, sdtContent));
+				},
+				bookmarkStart: (child) => {
+					placeBookmarkMarker(parseBookmarkStart(child));
+				},
+				bookmarkEnd: (child) => {
+					placeBookmarkMarker(parseBookmarkEnd(child));
+				},
+				trPr: OWNED_ELSEWHERE,
+				tblPrEx: OWNED_ELSEWHERE,
+				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,
+				tr: CAPTURE
 			}
-			row.cells.push(cell);
-			return;
-		}
-		if (localName === "sdt") {
-			const sdtContent = findChildByLocalName(child, "sdtContent");
-			if (!sdtContent) return;
-			const sdtContentOptions = withContainerXmlns(withContainerXmlns(childOptions, child), sdtContent);
-			for (const sdtChild of getChildElements(sdtContent)) parseRowChild(sdtChild, sdtContentOptions);
-			return;
-		}
-		if (localName !== "bookmarkStart" && localName !== "bookmarkEnd") return;
-		const marker = parseBookmarkMarker(child, localName);
+		});
+		if (captured?.children) preservedChildren.push(...captured.children);
+	};
+	const placeBookmarkMarker = (marker) => {
 		if (!appendBookmarkMarkerToLastParagraphInCells(row.cells, marker)) pendingBookmarkMarkers.push(marker);
 	};
-	for (const child of getChildElements(trElement)) parseRowChild(child);
+	dispatchRowChildren(trElement, rowOptions);
+	if (preservedChildren.length > 0) row.preserved = { children: preservedChildren };
+	const remainingAttributes = attributeRemainder({
+		element: trElement,
+		modelled: NO_MODELLED_ATTRIBUTES
+	});
+	if (remainingAttributes) row.preservedAttributes = remainingAttributes;
 	if (pendingBookmarkMarkers.length > 0) appendBookmarkMarkersToLastCell(row, pendingBookmarkMarkers);
 	return row;
 }
@@ -707,23 +786,65 @@ function parseTable(tblElement, styles, theme, numbering, rels, media, options)
 	}
 	const tableOptions = withContainerXmlns(options, tblElement);
 	const rowsWithGridOffsets = /* @__PURE__ */ new Set();
-	const parseTableChild = (child, childOptions = tableOptions) => {
-		const localName = getLocalName(child.name);
-		if (localName === "tr") {
-			const rowIndex = table.rows.length;
-			const row = parseTableRow(child, styles, theme, numbering, rels, media, childOptions);
-			table.rows.push(row);
-			if (hasRowGridOffsets(child)) rowsWithGridOffsets.add(rowIndex);
-			return;
-		}
-		if (localName !== "sdt") return;
-		const sdtContent = findChildByLocalName(child, "sdtContent");
-		if (!sdtContent) return;
-		const sdtContentOptions = withContainerXmlns(withContainerXmlns(childOptions, child), sdtContent);
-		for (const sdtChild of getChildElements(sdtContent)) parseTableChild(sdtChild, sdtContentOptions);
+	const preservedChildren = [];
+	/**
+	* One table's children, or a row-level content control's.
+	*
+	* folio unwraps `w:sdt` here and splices its rows into the table, so the
+	* recursion walks the control's content with the same map; the sink is the
+	* table's either way, because the control keeps no wrapper to hold one.
+	*/
+	const dispatchTableChildren = (element, childOptions) => {
+		const captured = dispatchChildren({
+			element,
+			container: "table-content",
+			modelledCount: () => table.rows.length,
+			handlers: {
+				tr: (child) => {
+					const rowIndex = table.rows.length;
+					table.rows.push(parseTableRow(child, styles, theme, numbering, rels, media, childOptions));
+					if (hasRowGridOffsets(child)) rowsWithGridOffsets.add(rowIndex);
+				},
+				sdt: (child) => {
+					const sdtContent = findChildByLocalName(child, "sdtContent");
+					if (!sdtContent) return;
+					const sdtOptions = withContainerXmlns(childOptions, child);
+					dispatchTableChildren(sdtContent, withContainerXmlns(sdtOptions, sdtContent));
+				},
+				tblPr: OWNED_ELSEWHERE,
+				tblGrid: OWNED_ELSEWHERE,
+				bookmarkEnd: CAPTURE,
+				bookmarkStart: CAPTURE,
+				commentRangeEnd: CAPTURE,
+				commentRangeStart: CAPTURE,
+				customXml: CAPTURE,
+				customXmlPr: 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
+			}
+		});
+		if (captured?.children) preservedChildren.push(...captured.children);
 	};
-	for (const child of getChildElements(tblElement)) parseTableChild(child);
+	dispatchTableChildren(tblElement, tableOptions);
 	if (table.rows.length === 0) return;
+	if (preservedChildren.length > 0) table.preserved = { children: preservedChildren };
 	inferImplicitSingleCellRowSpans(table, rowsWithGridOffsets);
 	return table;
 }

package/dist/docx/textBoxParser.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";
 //#region src/docx/textBoxParser.d.ts
 /**
  * Extract raw paragraph elements from w:txbxContent
@@ -112,5 +112,28 @@ declare function resolveTextBoxOutlineColor(textBox: document_d_exports.TextBox)
  * Get outline width in pixels
  */
 declare function getTextBoxOutlineWidthPx(textBox: document_d_exports.TextBox): number;
+type TextBoxRunScan = {
+  textBoxDrawings: XmlElement[];
+  vmlTextBoxes: XmlElement[];
+  hasNonTextBoxContent: boolean;
+};
+/**
+ * What a run's markup holds for the text-box pass, by kind.
+ *
+ * Two readers need this answer and they must not drift: the enrichment pass
+ * claims these elements, and `parseParagraphContents` has to keep the run they
+ * sit in even though the run parses to nothing until the pass fills it. It
+ * lives here, with `isTextBoxDrawing` and `parseTextBox`, so there is one.
+ */
+type ScanRunForTextBoxDrawingsOptions = {
+  xmlRun: XmlElement;
+  /**
+   * `isVmlPictParsedByRunParser`, passed rather than imported: the run parser
+   * reaches this module through the image parsers, so reading it from here
+   * would close a cycle.
+   */
+  claimedByRunParser: (pictElement: XmlElement) => boolean;
+};
+declare const scanRunForTextBoxDrawings: ({ xmlRun, claimedByRunParser }: ScanRunForTextBoxDrawingsOptions) => TextBoxRunScan;
 //#endregion
-export { ParagraphParserFn, TableParserFn, extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor };
+export { ParagraphParserFn, ScanRunForTextBoxDrawingsOptions, TableParserFn, TextBoxRunScan, extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor, scanRunForTextBoxDrawings };