@stll/folio-core 0.52.0 → 0.53.0

package/dist/document-operations.js

@@ -1,5 +1,10 @@
-import { applyFolioAIEditOperations, previewFolioAIEditOperations } from "./ai-edits/apply.js";
+import { applyFolioAIEditOperations, previewFolioAIEditOperationsWithResult } from "./ai-edits/apply.js";
+import { describeModelError, findIntroducedModelErrors } from "./ai-edits/result-validation.js";
+import { LIST_KINDS } from "./docx/listNumberingInstances.js";
 import { isNumberingReference } from "./docx/numberingReference.js";
+import { completeNumberingForDoc } from "./prosemirror/listInstanceReferences.js";
+import { outlineLevelFromAttrValue } from "./prosemirror/outlineLevelAttr.js";
+import { getStatedDocumentNumbering } from "./prosemirror/plugins/documentNumbering.js";
 import { LINE_SPACING_RULE_VALUES, PARAGRAPH_ALIGNMENT_VALUES } from "./types/documentEnumValues.js";
 import { TaggedError } from "better-result";
 import { sanitizeXmlCharacters } from "@stll/docx-core";
@@ -293,11 +298,40 @@ const readClearableParagraphIndentation = ({ value, key, path }) => {
 	}
 	return indentation;
 };
+/** `w:ilvl` names one of an abstract numbering's nine levels. */
+const MAX_NEW_LIST_LEVEL = 8;
+const LIST_KIND_SET = new Set(LIST_KINDS);
+const isListKind = (value) => LIST_KIND_SET.has(value);
+/** `{ start: "new", kind, level? }`: a list the operation starts. */
+const readNewListReference = (candidate, numberingPath) => {
+	assertAllowedKeys(candidate, numberingPath, [
+		"start",
+		"kind",
+		"level"
+	]);
+	const kind = candidate["kind"];
+	if (typeof kind !== "string" || !isListKind(kind)) return invalidBatch(`${numberingPath}.kind`, `expected one of ${LIST_KINDS.join(", ")}`);
+	if (candidate["level"] === void 0) return {
+		start: "new",
+		kind
+	};
+	const level = readNonNegativeInteger(candidate, "level", numberingPath);
+	if (level > MAX_NEW_LIST_LEVEL) return invalidBatch(`${numberingPath}.level`, `expected at most ${MAX_NEW_LIST_LEVEL}`);
+	return {
+		start: "new",
+		kind,
+		level
+	};
+};
 const readClearableNumbering = ({ value, key, path }) => {
 	const candidate = value[key];
 	if (candidate === void 0 || candidate === null) return candidate;
 	const numberingPath = `${path}.${key}`;
 	if (!isPlainObject(candidate)) return invalidBatch(numberingPath, "expected an object or null when provided");
+	if (candidate["start"] !== void 0) {
+		if (candidate["start"] !== "new") return invalidBatch(`${numberingPath}.start`, "expected \"new\"");
+		return readNewListReference(candidate, numberingPath);
+	}
 	assertAllowedKeys(candidate, numberingPath, ["numId", "level"]);
 	const numId = readNonNegativeInteger(candidate, "numId", numberingPath);
 	if (!isNumberingReference(numId)) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
@@ -326,12 +360,22 @@ const readTableRows = (value, path) => {
 	if (parsed.some((row) => row.length !== width)) return invalidBatch(rowsPath, "expected every row to hold the same number of cells");
 	return parsed;
 };
+const readClearableOutlineLevel = (value, path) => {
+	const candidate = value["outlineLevel"];
+	if (candidate === void 0 || candidate === null) return candidate;
+	if (!isPlainObject(candidate)) return invalidBatch(`${path}.outlineLevel`, "expected an outline level");
+	assertAllowedKeys(candidate, `${path}.outlineLevel`, ["kind", "level"]);
+	const outlineLevel = outlineLevelFromAttrValue(candidate);
+	if (outlineLevel === null) return invalidBatch(`${path}.outlineLevel`, "expected a valid outline level");
+	return outlineLevel;
+};
 const readParagraphProperties = ({ value, key, path }) => {
 	const candidate = value[key];
 	const propertiesPath = `${path}.${key}`;
 	if (!isPlainObject(candidate)) return invalidBatch(propertiesPath, "expected an object");
 	assertAllowedKeys(candidate, propertiesPath, [
 		"styleId",
+		"outlineLevel",
 		"listLevel",
 		"numbering",
 		"alignment",
@@ -339,6 +383,7 @@ const readParagraphProperties = ({ value, key, path }) => {
 		"indentation"
 	]);
 	const styleId = candidate["styleId"] === null ? null : readOptionalString(candidate, "styleId", propertiesPath);
+	const outlineLevel = readClearableOutlineLevel(candidate, propertiesPath);
 	const listLevel = readClearableNonNegativeInteger(candidate, "listLevel", propertiesPath);
 	const numbering = readClearableNumbering({
 		value: candidate,
@@ -360,9 +405,10 @@ const readParagraphProperties = ({ value, key, path }) => {
 		key: "indentation",
 		path: propertiesPath
 	});
-	if (styleId === void 0 && listLevel === void 0 && numbering === void 0 && alignment === void 0 && spacing === void 0 && indentation === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
+	if (styleId === void 0 && outlineLevel === void 0 && listLevel === void 0 && numbering === void 0 && alignment === void 0 && spacing === void 0 && indentation === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
 	return {
 		...styleId !== void 0 && { styleId },
+		...outlineLevel !== void 0 && { outlineLevel },
 		...listLevel !== void 0 && { listLevel },
 		...numbering !== void 0 && { numbering },
 		...alignment !== void 0 && { alignment },
@@ -515,6 +561,7 @@ const OPERATION_KEY_DECISIONS = {
 		pageBreakBefore: true,
 		hardPageBreak: true,
 		styleId: true,
+		outlineLevel: true,
 		comment: true
 	},
 	insertBeforeBlock: {
@@ -532,6 +579,7 @@ const OPERATION_KEY_DECISIONS = {
 		pageBreakBefore: true,
 		hardPageBreak: true,
 		styleId: true,
+		outlineLevel: true,
 		comment: true
 	},
 	replaceBlock: {
@@ -783,6 +831,7 @@ const parseDocumentOperation = (value, index) => {
 		const pageBreakBefore = readOptionalBoolean(value, "pageBreakBefore", path);
 		const hardPageBreak = readOptionalHardPageBreak(value, path);
 		const styleId = value["styleId"] === null ? null : readOptionalString(value, "styleId", path);
+		const outlineLevel = readClearableOutlineLevel(value, path);
 		const moveId = readOptionalString(value, "moveId", path);
 		const listLevel = readClearableNonNegativeInteger(value, "listLevel", path);
 		const numbering = readClearableNumbering({
@@ -810,7 +859,7 @@ const parseDocumentOperation = (value, index) => {
 		const formattingScope = value["formattingScope"];
 		if (formattingScope !== void 0 && formattingScope !== "firstParagraph" && formattingScope !== "allParagraphs") return invalidBatch(`${path}.formattingScope`, "expected \"firstParagraph\" or \"allParagraphs\" when provided");
 		const text = readString(value, "text", path);
-		if (hardPageBreak !== void 0 && text.length > 0) return invalidBatch(`${path}.text`, "expected empty text with hardPageBreak");
+		if (hardPageBreak !== void 0 && text.length > 0) return invalidBatch(`${path}.text`, "omit hardPageBreak to insert text, or set text to \"\" to insert a hard page break");
 		if (hardPageBreak !== void 0 && pageBreakBefore !== void 0) return invalidBatch(`${path}.pageBreakBefore`, "cannot combine hardPageBreak with pageBreakBefore");
 		if (hardPageBreak !== void 0 && lineBreakMode !== void 0) return invalidBatch(`${path}.lineBreakMode`, "cannot combine hardPageBreak with lineBreakMode");
 		return {
@@ -831,6 +880,7 @@ const parseDocumentOperation = (value, index) => {
 			...pageBreakBefore !== void 0 && { pageBreakBefore },
 			...hardPageBreak !== void 0 && { hardPageBreak },
 			...styleId !== void 0 && { styleId },
+			...outlineLevel !== void 0 && { outlineLevel },
 			...comment !== void 0 && { comment }
 		};
 	}
@@ -1014,22 +1064,31 @@ const recoveryByReason = {
 	pendingRunPropertyChange: "resolveTrackedChange",
 	noopOperation: "removeOperation",
 	documentVersionMismatch: "refreshDocument",
-	documentNotEditable: "retryLater"
+	documentNotEditable: "retryLater",
+	payloadDoesNotFit: "changeTarget",
+	overlappingOperation: "refreshDocument",
+	splitsCharacter: "changeTarget",
+	protectedReference: "narrowMatch",
+	missingStyle: "refreshDocument",
+	missingNumbering: "refreshDocument",
+	invalidResult: "refreshDocument",
+	pendingDeletion: "resolveTrackedChange"
 };
 const getFolioDocumentOperationIssues = (operations, skipped) => {
 	const indexById = /* @__PURE__ */ new Map();
 	operations.forEach(({ id }, index) => {
 		indexById.set(id, index);
 	});
-	return skipped.map(({ id, reason }) => {
+	return skipped.map(({ id, reason, message }) => {
 		const operationIndex = indexById.get(id) ?? -1;
 		return {
 			operationId: id,
 			operationIndex,
 			path: `$.operations[${operationIndex}]`,
 			code: reason,
-			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange",
-			recovery: recoveryByReason[reason]
+			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
+			recovery: recoveryByReason[reason],
+			...message !== void 0 && { message }
 		};
 	});
 };
@@ -1183,26 +1242,173 @@ const getFolioDocumentOperationReceiptsForStory = ({ operations, applied, story
 	});
 	return receipts;
 };
-const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground }) => {
+const NO_COMMIT = () => {};
+/** Skips reported in the order of the operations they belong to. */
+const inOperationOrder = (operations, skipped) => {
+	const indexById = new Map(operations.map(({ id }, index) => [id, index]));
+	return [...skipped].sort((left, right) => (indexById.get(left.id) ?? -1) - (indexById.get(right.id) ?? -1));
+};
+const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }) => {
 	const parsedBatch = parseFolioDocumentOperationBatch(batch);
-	const apply = ({ targetView, targetCreateCommentId = createCommentId, preview = false }) => {
-		return (preview ? previewFolioAIEditOperations : applyFolioAIEditOperations)({
-			view: targetView,
+	const isAtomic = parsedBatch.atomic === true;
+	const beforeDoc = view.state.doc;
+	const packageNumbering = getStatedDocumentNumbering(view.state);
+	const attempt = (operations, preview) => {
+		const common = {
 			snapshot,
-			operations: parsedBatch.operations,
+			operations,
 			mode: parsedBatch.mode ?? "tracked-changes",
 			...author !== void 0 && { author },
-			...targetCreateCommentId !== void 0 && { createCommentId: targetCreateCommentId },
 			...revisionStamp !== void 0 && { revisionStamp },
 			...wordDiff !== void 0 && { wordDiff },
 			...tableTemplates !== void 0 && { tableTemplates },
-			...replacementBackground !== void 0 && { replacementBackground }
+			...replacementBackground !== void 0 && { replacementBackground },
+			...undefinedStyles !== void 0 && { undefinedStyles }
+		};
+		if (preview) return {
+			...previewFolioAIEditOperationsWithResult({
+				...common,
+				view,
+				...createCommentId !== void 0 && { createCommentId }
+			}),
+			commit: NO_COMMIT
+		};
+		const held = {};
+		const commentIds = [];
+		return {
+			outcome: applyFolioAIEditOperations({
+				...common,
+				view: {
+					state: view.state,
+					dispatch: (transaction) => {
+						held.transaction = transaction;
+					}
+				},
+				...createCommentId !== void 0 && { createCommentId: (text) => {
+					const id = createCommentId(text);
+					commentIds.push(id);
+					return id;
+				} }
+			}),
+			doc: held.transaction?.doc ?? null,
+			commentIds,
+			commit: () => {
+				if (held.transaction !== void 0) view.dispatch(held.transaction);
+			}
+		};
+	};
+	const introducedErrors = (run) => {
+		if (run.doc === null || run.outcome.applied.length === 0) return [];
+		const numbering = packageNumbering === void 0 ? void 0 : completeNumberingForDoc(packageNumbering ?? void 0, run.doc) ?? null;
+		return findIntroducedModelErrors(beforeDoc, run.doc, {
+			numbering,
+			createdCommentIds: run.commentIds,
+			...author !== void 0 && { commentAuthor: author }
 		});
 	};
-	const preview = () => apply({
-		targetView: view,
-		preview: true
-	});
+	/**
+	* An attempt on the refusal path, where the applier runs on subsets of the
+	* batch it was not asked to apply: a throw there is one more reason to
+	* refuse, never a reason to fail a batch the first run could apply.
+	*/
+	const checkedAttempt = (operations, preview) => {
+		try {
+			const run = attempt(operations, preview);
+			return {
+				run,
+				error: introducedErrors(run)[0]
+			};
+		} catch (error) {
+			return {
+				run: null,
+				error: {
+					path: "package.document",
+					message: `the operation could not be applied (${error instanceof Error ? error.message : String(error)}).`,
+					severity: "error"
+				}
+			};
+		}
+	};
+	/**
+	* Which applied operations produced the unsaveable result: each one is
+	* previewed alone against the unchanged story. When none fails alone, the
+	* failure is their combination, and every one of them is refused.
+	*/
+	const refuseInvalidResult = (run, firstError) => {
+		const operationsById = new Map(parsedBatch.operations.map((operation) => [operation.id, operation]));
+		const refused = [];
+		for (const { id } of run.outcome.applied) {
+			const operation = operationsById.get(id);
+			if (operation === void 0) continue;
+			const alone = checkedAttempt([operation], true).error;
+			if (alone !== void 0) refused.push({
+				id,
+				reason: "invalidResult",
+				message: describeModelError(alone)
+			});
+		}
+		if (refused.length > 0) return refused;
+		return run.outcome.applied.map(({ id }) => ({
+			id,
+			reason: "invalidResult",
+			message: describeModelError(firstError)
+		}));
+	};
+	/**
+	* Apply (or preview) the batch and check the result with the save-time
+	* validator before anything reaches the caller. Operations whose result would
+	* not save are skipped with `invalidResult`; in a best-effort batch the rest
+	* is applied again without them, in an atomic one nothing is.
+	*/
+	const guardedAttempt = (preview) => {
+		const first = attempt(parsedBatch.operations, preview);
+		const [firstError] = introducedErrors(first);
+		if (firstError === void 0) return {
+			outcome: {
+				...first.outcome,
+				skipped: inOperationOrder(parsedBatch.operations, first.outcome.skipped)
+			},
+			commit: first.commit
+		};
+		const refused = refuseInvalidResult(first, firstError);
+		const refusedIds = new Set(refused.map(({ id }) => id));
+		if (isAtomic) return {
+			outcome: {
+				...first.outcome,
+				applied: [],
+				skipped: inOperationOrder(parsedBatch.operations, [...first.outcome.skipped, ...refused])
+			},
+			commit: NO_COMMIT
+		};
+		const second = checkedAttempt(parsedBatch.operations.filter(({ id }) => !refusedIds.has(id)), preview);
+		if (second.run === null || second.error !== void 0) {
+			const reported = second.run?.outcome ?? first.outcome;
+			return {
+				outcome: {
+					...reported,
+					applied: [],
+					skipped: inOperationOrder(parsedBatch.operations, [
+						...reported.skipped.filter(({ id }) => !refusedIds.has(id)),
+						...refused,
+						...reported.applied.filter(({ id }) => !refusedIds.has(id)).map(({ id }) => ({
+							id,
+							reason: "invalidResult",
+							message: describeModelError(second.error ?? firstError)
+						}))
+					])
+				},
+				commit: NO_COMMIT
+			};
+		}
+		return {
+			outcome: {
+				...second.run.outcome,
+				skipped: inOperationOrder(parsedBatch.operations, [...second.run.outcome.skipped, ...refused])
+			},
+			commit: second.run.commit
+		};
+	};
+	const preview = () => guardedAttempt(true).outcome;
 	const atomicResult = (previewResult, status) => {
 		const skippedById = new Map(previewResult.skipped.map((operation) => [operation.id, operation]));
 		const skipped = parsedBatch.operations.map(({ id }) => skippedById.get(id) ?? {
@@ -1223,7 +1429,7 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 	};
 	if (parsedBatch.dryRun === true) {
 		const previewResult = preview();
-		if (parsedBatch.atomic === true && previewResult.skipped.length > 0) return atomicResult(previewResult, "previewed");
+		if (isAtomic && previewResult.skipped.length > 0) return atomicResult(previewResult, "previewed");
 		return {
 			version: 1,
 			status: "previewed",
@@ -1240,11 +1446,14 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 			nextRevisionId: previewResult.nextRevisionId
 		};
 	}
-	if (parsedBatch.atomic === true) {
+	if (isAtomic) {
 		const previewResult = preview();
 		if (previewResult.skipped.length > 0) return atomicResult(previewResult, "rejected");
 	}
-	const result = apply({ targetView: view });
+	const guarded = guardedAttempt(false);
+	const result = guarded.outcome;
+	if (isAtomic && result.skipped.some(({ reason }) => reason === "invalidResult")) return atomicResult(result, "rejected");
+	guarded.commit();
 	return {
 		version: 1,
 		status: "committed",

package/dist/docx/altChunk.d.ts

@@ -0,0 +1,8 @@
+//#region src/docx/altChunk.d.ts
+declare const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
+declare const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1000000;
+/** The captured fragment's expanded name, not its source prefix, identifies w:altChunk. */
+declare const isAltChunkMarkup: (xml: string) => boolean;
+declare const getAltChunkRelationshipId: (xml: string) => string | undefined;
+//#endregion
+export { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, ALT_CHUNK_READER_DIAGNOSTIC, getAltChunkRelationshipId, isAltChunkMarkup };

package/dist/docx/altChunk.js

@@ -0,0 +1,17 @@
+import { OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, getAttribute, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+//#region src/docx/altChunk.ts
+const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
+const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1e6;
+const OFFICE_RELATIONSHIPS_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** The captured fragment's expanded name, not its source prefix, identifies w:altChunk. */
+const isAltChunkMarkup = (xml) => {
+	const element = getChildElements(parseXml(xml, OOXML_NAMESPACE_SCOPE)).at(0);
+	return element?.type === "element" && getLocalName(element.name) === "altChunk" && WORDPROCESSINGML_NAMESPACE_URIS.has(element.namespaceUri ?? "");
+};
+const getAltChunkRelationshipId = (xml) => {
+	const element = getChildElements(parseXml(xml, OOXML_NAMESPACE_SCOPE)).at(0);
+	if (element?.type !== "element" || getLocalName(element.name) !== "altChunk" || !WORDPROCESSINGML_NAMESPACE_URIS.has(element.namespaceUri ?? "")) return;
+	return getAttribute(element, OFFICE_RELATIONSHIPS_NAMESPACE_URI, "id") ?? void 0;
+};
+//#endregion
+export { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, ALT_CHUNK_READER_DIAGNOSTIC, getAltChunkRelationshipId, isAltChunkMarkup };

package/dist/docx/attributeRemainder.d.ts

@@ -1,5 +1,5 @@
-import { ModelledAttributes } from "./propertyElementAttributes.js";
 import { XmlElement } from "./xmlParser.js";
+import { ModelledAttributes } from "./propertyElementAttributes.js";
 import { PreservedAttribute } from "@stll/docx-core/model";
 //#region src/docx/attributeRemainder.d.ts
 declare const InvalidPreservedAttributeError_base: import("better-result").TaggedErrorClass<"InvalidPreservedAttributeError">;

package/dist/docx/blockContentParser.d.ts

@@ -2,6 +2,7 @@ import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
+import { OwnedElsewhere } from "./containerChildren.js";
 import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/blockContentParser.d.ts
@@ -11,6 +12,68 @@ type ParseBlockContentOptions = {
   context?: ParseContext | undefined;
   previews?: PreviewLedger;
 };
+/** The options every block below the entry point reads, with its ledger settled. */
+type BlockContentScope = ParseBlockContentOptions & {
+  previews: PreviewLedger;
+};
+type PreviousListState = {
+  abstractNumId: number | null;
+  fromStyle: boolean;
+  numId: number | null;
+};
+type ParseBlockContentState = {
+  listCounters: Map<number, number[]>;
+  abstractCounters: Map<number, number[]>;
+  restartedNumIds: Set<number>;
+  previousList: PreviousListState;
+  options: BlockContentScope;
+};
 declare const parseBlockContent: (parent: 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, options?: ParseBlockContentOptions) => document_d_exports.BlockContent[];
+/** The parts and maps a block sequence is read against. */
+type BlockContentResources = {
+  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;
+};
+/** One block container's children as they are read. */
+type BlockContentWalk = {
+  resources: BlockContentResources;
+  state: ParseBlockContentState;
+  modelled: document_d_exports.BlockContent[];
+};
+declare const BLOCK_CONTENT_HANDLERS: {
+  readonly altChunk: "capture";
+  readonly commentRangeEnd: "capture";
+  readonly commentRangeStart: "capture";
+  readonly customXmlDelRangeEnd: "capture";
+  readonly customXmlDelRangeStart: "capture";
+  readonly customXmlInsRangeEnd: "capture";
+  readonly customXmlInsRangeStart: "capture";
+  readonly customXmlMoveFromRangeEnd: "capture";
+  readonly customXmlMoveFromRangeStart: "capture";
+  readonly customXmlMoveToRangeEnd: "capture";
+  readonly customXmlMoveToRangeStart: "capture";
+  readonly del: "capture";
+  readonly ins: "capture";
+  readonly moveFrom: "capture";
+  readonly moveFromRangeEnd: "capture";
+  readonly moveFromRangeStart: "capture";
+  readonly moveTo: "capture";
+  readonly moveToRangeEnd: "capture";
+  readonly moveToRangeStart: "capture";
+  readonly permEnd: "capture";
+  readonly permStart: "capture";
+  readonly proofErr: "capture";
+  readonly sectPr: OwnedElsewhere<"block-content", "sectPr">;
+  readonly tcPr: OwnedElsewhere<"block-content", "tcPr">;
+  readonly p: (child: XmlElement, { resources: { styles, theme, numbering, rels, media }, state, modelled }: BlockContentWalk) => void;
+  readonly tbl: (child: XmlElement, { resources: { styles, theme, numbering, rels, media }, state, modelled }: BlockContentWalk) => "capture" | undefined;
+  readonly sdt: (child: XmlElement, { resources: { styles, theme, numbering, rels, media }, state, modelled }: BlockContentWalk) => void;
+  readonly customXml: (child: XmlElement, { resources: { styles, theme, numbering, rels, media }, state, modelled }: BlockContentWalk) => void;
+  readonly bookmarkStart: (child: XmlElement, { modelled }: BlockContentWalk) => void;
+  readonly bookmarkEnd: (child: XmlElement, { modelled }: BlockContentWalk) => void;
+};
 //#endregion
-export { parseBlockContent };
+export { BLOCK_CONTENT_HANDLERS, parseBlockContent };

package/dist/docx/blockContentParser.js

@@ -1,3 +1,4 @@
+import { blockCustomXmlShell } from "./blockCustomXmlShell.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { bulletMarkerFontName, convertBulletToUnicode } from "./bulletMarkers.js";
 import { CAPTURE, dispatchChildrenWithContext, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
@@ -8,7 +9,7 @@ import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { standalonePreviewLedger } from "./previewBudget.js";
 import { captureSdtSiblingMarkers, parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
-import { findWordprocessingChild, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
+import { findWordprocessingChild, getLocalName, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
 //#region src/docx/blockContentParser.ts
 const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList }) => {
 	const listRendering = paragraph.listRendering;
@@ -131,6 +132,13 @@ const BLOCK_CONTENT_UNDECLARED = { AlternateContent: (child, { resources: { styl
 	if (!selectedBranch) return;
 	modelled.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
 } };
+const parseBlockCustomXml = (child, styles, theme, numbering, rels, media, state) => {
+	return {
+		type: "blockCustomXml",
+		...blockCustomXmlShell(child),
+		content: parseBlockContentWithState(child, styles, theme, numbering, rels, media, withContainerXmlns(state, child))
+	};
+};
 const BLOCK_CONTENT_HANDLERS = {
 	p: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
 		const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, {
@@ -149,12 +157,18 @@ const BLOCK_CONTENT_HANDLERS = {
 	},
 	tbl: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
 		const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
-		if (!table) return;
+		if (!table) return child.elements?.some((tableChild) => {
+			const localName = getLocalName(tableChild.name ?? "");
+			return localName !== "tblPr" && localName !== "tblGrid";
+		}) ?? false ? CAPTURE : void 0;
 		modelled.push(table);
 	},
 	sdt: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
 		modelled.push(parseBlockSdt(child, styles, theme, numbering, rels, media, state));
 	},
+	customXml: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
+		modelled.push(parseBlockCustomXml(child, styles, theme, numbering, rels, media, state));
+	},
 	bookmarkStart: (child, { modelled }) => {
 		modelled.push(parseBookmarkStart(child));
 	},
@@ -165,7 +179,6 @@ const BLOCK_CONTENT_HANDLERS = {
 	altChunk: CAPTURE,
 	commentRangeEnd: CAPTURE,
 	commentRangeStart: CAPTURE,
-	customXml: CAPTURE,
 	customXmlDelRangeEnd: CAPTURE,
 	customXmlDelRangeStart: CAPTURE,
 	customXmlInsRangeEnd: CAPTURE,
@@ -223,4 +236,4 @@ const parseBlockSdt = (child, styles, theme, numbering, rels, media, state) => {
 	};
 };
 //#endregion
-export { parseBlockContent };
+export { BLOCK_CONTENT_HANDLERS, parseBlockContent };

package/dist/docx/blockCustomXmlShell.d.ts

@@ -0,0 +1,7 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/blockCustomXmlShell.d.ts
+/** Capture the wrapper independently of its modeled and preserved children. */
+declare const blockCustomXmlShell: (element: XmlElement) => Pick<document_d_exports.BlockCustomXml, "openingXml" | "closingXml">;
+//#endregion
+export { blockCustomXmlShell };

package/dist/docx/blockCustomXmlShell.js

@@ -0,0 +1,14 @@
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { cloneElement } from "./xmlParser.js";
+//#region src/docx/blockCustomXmlShell.ts
+/** Capture the wrapper independently of its modeled and preserved children. */
+const blockCustomXmlShell = (element) => {
+	const shell = captureVerbatimXml(cloneElement(element, { elements: [] }));
+	const name = element.name ?? "w:customXml";
+	return {
+		openingXml: shell.endsWith("/>") ? `${shell.slice(0, -2)}>` : shell,
+		closingXml: `</${name}>`
+	};
+};
+//#endregion
+export { blockCustomXmlShell };

package/dist/docx/blockPlainText.js

@@ -1,3 +1,5 @@
+import { ALT_CHUNK_READER_DIAGNOSTIC, isAltChunkMarkup } from "./altChunk.js";
+import { OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC, isOpaqueNestedRowMarkup, opaqueRevisionCarrierName } from "./opaqueCarrier.js";
 import { getParagraphText } from "./paragraphParser.js";
 import { panic } from "better-result";
 //#region src/docx/blockPlainText.ts
@@ -29,9 +31,14 @@ const collectBlockTexts = (blocks) => {
 			}
 			break;
 		case "blockSdt":
+		case "blockCustomXml":
 			texts.push(...collectBlockTexts(block.content));
 			break;
 		case "preservedBlock":
+			if (isAltChunkMarkup(block.xml)) texts.push(block.readerText === void 0 ? ALT_CHUNK_READER_DIAGNOSTIC : `${ALT_CHUNK_READER_DIAGNOSTIC}\n${block.readerText}`);
+			else if (opaqueRevisionCarrierName(block.xml) !== void 0) texts.push(OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC);
+			else if (isOpaqueNestedRowMarkup(block.xml)) texts.push("[Unsupported nested w:tr content]");
+			break;
 		case "bookmarkStart":
 		case "bookmarkEnd": break;
 		default: panic(`Unsupported block in plain-text extraction: ${JSON.stringify(block)}`);

package/dist/docx/commentAnchorIndex.js

@@ -19,7 +19,7 @@ const visitCommentMarkers = (blocks, visit) => {
 			for (const row of block.rows) for (const cell of row.cells) visitBlocks(cell.content);
 			return;
 		}
-		if (block.type !== "blockSdt") return;
+		if (block.type !== "blockSdt" && block.type !== "blockCustomXml") return;
 		visitBlocks(block.content);
 	};
 	const visitBlocks = (nested) => {

package/dist/docx/commentRangeIntegrity.js

@@ -1,6 +1,11 @@
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 //#region src/docx/commentRangeIntegrity.ts
-const COMMENT_RANGE_MARKER_PATTERN = /<w:commentRange(Start|End)\s[^>]*w:id="(\d+)"/gu;
+/**
+* A range marker under any prefix, or none: this is the guard a splice is
+* refused by, and a guard that only knows `w:` passes every patch of a part
+* that spells WordprocessingML another way.
+*/
+const COMMENT_RANGE_MARKER_PATTERN = /<(?:[\w.-]+:)?commentRange(Start|End)(?:\s[^>]*?)?\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
@@ -147,7 +152,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 !== "blockSdt") return block;
+	if (block.type !== "blockSdt" && block.type !== "blockCustomXml") return block;
 	const content = withoutOrphanBlockMarkers(block.content, validCommentIds);
 	if (!content) return block;
 	return {
@@ -204,7 +209,7 @@ const withoutOrphanTableCellBlockMarkers = (blocks, validCommentIds) => {
 const withoutOrphanTableCellBlockMarker = (block, validCommentIds) => {
 	if (block.type === "paragraph") return withoutOrphanParagraphMarkers(block, validCommentIds);
 	if (block.type === "table") return withoutOrphanTableMarkers(block, validCommentIds);
-	if (block.type === "blockSdt") {
+	if (block.type === "blockSdt" || block.type === "blockCustomXml") {
 		const content = withoutOrphanTableCellBlockMarkers(block.content, validCommentIds);
 		return content ? {
 			...block,

package/dist/docx/commentReferenceNormalization.js

@@ -40,7 +40,7 @@ const normalizeCommentReferences = ({ documentBody, comments, headers, footers,
 			normalizeTable(block);
 			return;
 		}
-		if (block.type !== "blockSdt") return;
+		if (block.type !== "blockSdt" && block.type !== "blockCustomXml") return;
 		normalizeBlocks(block.content);
 	};
 	const normalizeBlocks = (blocks) => {