@stll/folio-core 0.37.1 → 0.37.3

package/dist/layout-engine/types.d.ts

@@ -604,6 +604,8 @@ type TableRow = {
   isHeader?: boolean;
   /** `w:cantSplit`: keep this row in one flow region. */
   cantSplit?: boolean;
+  /** A leading authored page break in a cell advances the whole row. */
+  breakBefore?: "page";
   hidden?: boolean;
 };
 /**
@@ -802,6 +804,8 @@ type TextBoxBlock = {
   outlineColor?: string;
   /** Outline dash style, or `"none"` for an explicit no-outline. */
   outlineStyle?: OutlineStyleAttr;
+  /** DrawingML rotation and/or flips, serialized as CSS transform functions. */
+  transform?: string;
   /** Internal padding */
   margins?: {
     top: number;
@@ -1032,6 +1036,8 @@ type FragmentBase = {
  */
 type ParagraphFragment = FragmentBase & {
   kind: "paragraph";
+  /** Structural PM carrier that must not make an otherwise blank page visible. */
+  paginationRole?: "empty-carrier";
   /** First line index (inclusive) from the measure. */
   fromLine: number;
   /** Last line index (exclusive) from the measure. */

package/dist/layout-painter/documentColors.d.ts

@@ -1,4 +1,13 @@
 //#region src/layout-painter/documentColors.d.ts
+declare const AUTHORED_BACKGROUND_COLOR_VAR = "--doc-authored-background-color";
+declare const AUTHORED_TEXT_COLOR_VAR = "--doc-run-color";
+/** Paint a document text color and expose it to the dark-mode color transform. */
+declare const setAuthoredTextColor: (style: CSSStyleDeclaration, color: string) => void;
+/**
+ * Paint an OOXML background and retain its authored color for dark-mode adaptation.
+ * The custom property is presentation-only; serialization still uses the model value.
+ */
+declare const setAuthoredBackgroundColor: (style: CSSStyleDeclaration, color: string) => void;
 declare function getAutomaticTextColorForBackground(backgroundColor: string | undefined): string | undefined;
 //#endregion
-export { getAutomaticTextColorForBackground };
+export { AUTHORED_BACKGROUND_COLOR_VAR, AUTHORED_TEXT_COLOR_VAR, getAutomaticTextColorForBackground, setAuthoredBackgroundColor, setAuthoredTextColor };

package/dist/layout-painter/documentColors.js

@@ -5,6 +5,21 @@ const WHITE_TEXT_COLOR = "#FFFFFF";
 const BLACK_LUMINANCE = 0;
 const WHITE_LUMINANCE = 1;
 const CONTRAST_OFFSET = .05;
+const AUTHORED_BACKGROUND_COLOR_VAR = "--doc-authored-background-color";
+const AUTHORED_TEXT_COLOR_VAR = "--doc-run-color";
+/** Paint a document text color and expose it to the dark-mode color transform. */
+const setAuthoredTextColor = (style, color) => {
+	style.color = color;
+	style.setProperty(AUTHORED_TEXT_COLOR_VAR, color);
+};
+/**
+* Paint an OOXML background and retain its authored color for dark-mode adaptation.
+* The custom property is presentation-only; serialization still uses the model value.
+*/
+const setAuthoredBackgroundColor = (style, color) => {
+	style.backgroundColor = color;
+	style.setProperty(AUTHORED_BACKGROUND_COLOR_VAR, color);
+};
 function normalizeHexColor(color) {
 	const trimmed = color.trim();
 	if (!HEX_COLOR_RE.test(trimmed)) return null;
@@ -37,4 +52,4 @@ function getAutomaticTextColorForBackground(backgroundColor) {
 	return contrastRatio(luminance, BLACK_LUMINANCE) >= contrastRatio(luminance, WHITE_LUMINANCE) ? BLACK_TEXT_COLOR : WHITE_TEXT_COLOR;
 }
 //#endregion
-export { getAutomaticTextColorForBackground };
+export { AUTHORED_BACKGROUND_COLOR_VAR, AUTHORED_TEXT_COLOR_VAR, getAutomaticTextColorForBackground, setAuthoredBackgroundColor, setAuthoredTextColor };

package/dist/layout-painter/renderParagraph.js

@@ -19,7 +19,7 @@ import { SCRIPT_CLASS, hasCjk, hasComplexScript, segmentByScript } from "../util
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
 import { borderStrokeToCss, resolveParagraphBorderHorizontalOutsets } from "./borderStroke.js";
 import { planCursiveJoiners, withCursiveJoiners } from "./cursiveJoiners.js";
-import { getAutomaticTextColorForBackground } from "./documentColors.js";
+import { getAutomaticTextColorForBackground, setAuthoredBackgroundColor, setAuthoredTextColor } from "./documentColors.js";
 import { applyImageBorder, applyImageVisualAttrs, hasImageCrop, hasImageVisualAttrs, wrapImageWithCrop } from "./renderImage.js";
 import { resolveImageLineAlign } from "./renderUtils.js";
 import { applySdtDataAttrs } from "./sdtBoundary.js";
@@ -124,12 +124,6 @@ const DEFAULT_BLACK_TEXT_COLOR_VALUES = /* @__PURE__ */ new Set(["000000", "000"
 const SUGGESTION_COLOR_CSS = "var(--suggestion-color, #6d3bd6)";
 const SUGGESTION_TINT_CSS = "var(--suggestion-bg, color-mix(in oklch, #6d3bd6 12%, transparent))";
 const SUGGESTION_TINT_LAYER_CSS = `linear-gradient(${SUGGESTION_TINT_CSS}, ${SUGGESTION_TINT_CSS})`;
-const RUN_BACKGROUND_TEXT_COLOR_VAR = "--doc-run-background-text-color";
-const setRunBackgroundTextColor = (element, color) => {
-	element.classList.add("docx-run-background-text");
-	element.style.setProperty(RUN_BACKGROUND_TEXT_COLOR_VAR, color);
-};
-const hasRunBackgroundTextSurface = (run) => Boolean(run.highlight ?? run.shading) && !run.isInsertion && !run.isDeletion && !(run.commentIds !== void 0 && run.commentIds.length > 0);
 function normalizeTextColorValue(color) {
 	return color.trim().toLowerCase().replace(/^#/u, "");
 }
@@ -180,8 +174,7 @@ function applyRunStyles(element, run) {
 	let hasExplicitTextColor = false;
 	const textColor = getRenderableTextColor(run);
 	if (textColor) {
-		element.style.color = textColor;
-		element.style.setProperty("--doc-run-color", textColor);
+		setAuthoredTextColor(element.style, textColor);
 		hasExplicitTextColor = true;
 	}
 	if (run.letterSpacing) element.style.letterSpacing = `${run.letterSpacing}px`;
@@ -219,13 +212,11 @@ function applyRunStyles(element, run) {
 	}
 	const runBackground = run.highlight ?? run.shading;
 	if (runBackground) {
-		element.style.backgroundColor = runBackground;
+		setAuthoredBackgroundColor(element.style, runBackground);
 		const hasTrackedChangeColor = run.isInsertion || run.isDeletion;
 		const hasCommentHighlight = run.commentIds !== void 0 && run.commentIds.length > 0;
 		const automaticTextColor = hasExplicitTextColor || hasTrackedChangeColor || hasCommentHighlight ? void 0 : getAutomaticTextColorForBackground(runBackground);
-		if (automaticTextColor) element.style.color = automaticTextColor;
-		const backgroundTextColor = hasExplicitTextColor ? textColor : automaticTextColor;
-		if (backgroundTextColor && hasRunBackgroundTextSurface(run)) setRunBackgroundTextColor(element, backgroundTextColor);
+		if (automaticTextColor) setAuthoredTextColor(element.style, automaticTextColor);
 	}
 	const decorations = [];
 	let explicitDecorationStyle = false;
@@ -378,15 +369,9 @@ function renderTextRun(run, doc, options) {
 		});
 		if (!run.hyperlink.noDefaultStyle) {
 			const hyperlinkColor = getHyperlinkTextColor(run, span.style.color);
-			anchor.style.color = hyperlinkColor;
+			setAuthoredTextColor(anchor.style, hyperlinkColor);
 			anchor.style.textDecoration = "underline";
-			span.style.color = hyperlinkColor;
-			anchor.style.setProperty("--doc-run-color", hyperlinkColor);
-			span.style.setProperty("--doc-run-color", hyperlinkColor);
-			if (hasRunBackgroundTextSurface(run)) {
-				setRunBackgroundTextColor(span, hyperlinkColor);
-				setRunBackgroundTextColor(anchor, hyperlinkColor);
-			}
+			setAuthoredTextColor(span.style, hyperlinkColor);
 		}
 		span.append(anchor);
 	} else appendPaintedText({
@@ -1295,7 +1280,7 @@ function renderLine(block, line, alignment, doc, options) {
 			}
 			const authoredEndpoint = currentX + tabResult.width + followingWidthForCheck;
 			const activeContentRightEdge = options?.contentWidthPx === void 0 ? void 0 : options.contentWidthPx - (options.floatingMargins?.rightMargin ?? 0);
-			const preservesAuthoredEndStop = activeContentRightEdge !== void 0 && tabResult.alignment === "end" && authoredEndpoint <= activeContentRightEdge + RIGHT_EDGE_EPSILON_PX;
+			const preservesAuthoredEndStop = activeContentRightEdge !== void 0 && tabResult.alignment === "end" && (options?.context?.section === "header" || options?.context?.section === "footer" || authoredEndpoint <= activeContentRightEdge + RIGHT_EDGE_EPSILON_PX);
 			const preservesAuthoredEndStopPastIndent = lineRightEdgeX !== void 0 && preservesAuthoredEndStop && authoredEndpoint > lineRightEdgeX + RIGHT_EDGE_EPSILON_PX;
 			if (lineRightEdgeX !== void 0 && options?.isRtl !== true && tabResult.alignment === "end" && !hasFollowingTab && !preservesAuthoredEndStopPastIndent && authoredEndpoint >= lineRightEdgeX - RIGHT_EDGE_EPSILON_PX) {
 				lineEl.style.display = "flex";
@@ -1534,9 +1519,9 @@ function renderParagraphFragment(fragment, block, measure, context, options = {}
 		}
 	}
 	if (block.attrs?.shading) {
-		fragmentEl.style.backgroundColor = block.attrs.shading;
+		setAuthoredBackgroundColor(fragmentEl.style, block.attrs.shading);
 		const automaticTextColor = getAutomaticTextColorForBackground(block.attrs.shading);
-		if (automaticTextColor) fragmentEl.style.color = automaticTextColor;
+		if (automaticTextColor) setAuthoredTextColor(fragmentEl.style, automaticTextColor);
 	}
 	const availableWidth = fragment.width - indentLeft - indentRight;
 	const paragraphEndsWithLineBreak = block.runs.at(-1)?.kind === "lineBreak";

package/dist/layout-painter/renderTable.js

@@ -9,7 +9,7 @@ import { applySanitizedImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { resolveAnchoredImagePosition } from "./anchoredImagePosition.js";
 import { borderStrokeToCss, resolveCssBorderStroke } from "./borderStroke.js";
-import { getAutomaticTextColorForBackground } from "./documentColors.js";
+import { getAutomaticTextColorForBackground, setAuthoredBackgroundColor, setAuthoredTextColor } from "./documentColors.js";
 import { applyImageVisualAttrs, hasImageCrop, hasImageVisualAttrs } from "./renderImage.js";
 import { renderParagraphFragment } from "./renderParagraph.js";
 import { renderTextBoxFragment } from "./renderTextBox.js";
@@ -394,9 +394,9 @@ function renderTableCell({ cell, cellMeasure, x, width, rowHeight, borderFlags,
 		if (borderFlags.drawLeft) applyBorder(cellEl, "left", cell.borders.left);
 	}
 	if (cell.background) {
-		cellEl.style.backgroundColor = cell.background;
+		setAuthoredBackgroundColor(cellEl.style, cell.background);
 		const automaticTextColor = getAutomaticTextColorForBackground(cell.background);
-		if (automaticTextColor) cellEl.style.color = automaticTextColor;
+		if (automaticTextColor) setAuthoredTextColor(cellEl.style, automaticTextColor);
 	}
 	if (cell.noWrap && !columnsPinned) cellEl.style.whiteSpace = "nowrap";
 	if (cell.verticalAlign) {

package/dist/layout-painter/renderTextBox.js

@@ -1,5 +1,6 @@
 import { layoutTextBoxContent } from "../layout-engine/measure/textBoxParagraphLayout.js";
 import { DEFAULT_TEXTBOX_MARGINS } from "../layout-engine/types.js";
+import { setAuthoredBackgroundColor } from "./documentColors.js";
 import { renderParagraphFragment } from "./renderParagraph.js";
 import { panic } from "better-result";
 //#region src/layout-painter/renderTextBox.ts
@@ -28,7 +29,7 @@ function renderTextBoxFragment(fragment, block, measure, context, options = {})
 	containerEl.style.height = `${fragment.height}px`;
 	containerEl.style.overflow = block.textWrap === "none" ? "visible" : "hidden";
 	containerEl.style.boxSizing = "border-box";
-	if (block.fillColor) containerEl.style.backgroundColor = block.fillColor;
+	if (block.fillColor) setAuthoredBackgroundColor(containerEl.style, block.fillColor);
 	if (block.outlineWidth && block.outlineWidth > 0) {
 		const style = block.outlineStyle || "solid";
 		const color = block.outlineColor || "#000000";

package/dist/pdf/pageSpace.d.ts

@@ -39,5 +39,16 @@ declare const displayPointToPdf: (pageHeightPx: number, xPx: number, yPx: number
  * screen, which is what a positive CSS/OOXML angle means.
  */
 declare const rotationMatrix: (degrees: number, originXPx: number, originYPx: number) => PdfMatrix;
+/**
+ * A DrawingML flip and rotation about one display-list point. CSS applies the
+ * rightmost scale first, then the rotation; this matrix does the same.
+ */
+declare const transformMatrix: ({ degrees, originXPx, originYPx, scaleX, scaleY }: {
+  readonly degrees: number;
+  readonly originXPx: number;
+  readonly originYPx: number;
+  readonly scaleX?: -1;
+  readonly scaleY?: -1;
+}) => PdfMatrix;
 //#endregion
-export { POINTS_PER_PIXEL, PdfMatrix, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix };
+export { POINTS_PER_PIXEL, PdfMatrix, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix, transformMatrix };

package/dist/pdf/pageSpace.js

@@ -53,5 +53,28 @@ const rotationMatrix = (degrees, originXPx, originYPx) => {
 		originYPx - originXPx * sin - originYPx * cos
 	];
 };
+/**
+* A DrawingML flip and rotation about one display-list point. CSS applies the
+* rightmost scale first, then the rotation; this matrix does the same.
+*/
+const transformMatrix = ({ degrees, originXPx, originYPx, scaleX, scaleY }) => {
+	const radians = degrees * Math.PI / 180;
+	const cos = Math.cos(radians);
+	const sin = Math.sin(radians);
+	const horizontalScale = scaleX ?? 1;
+	const verticalScale = scaleY ?? 1;
+	const a = cos * horizontalScale;
+	const b = sin * horizontalScale;
+	const c = -sin * verticalScale;
+	const d = cos * verticalScale;
+	return [
+		a,
+		b,
+		c,
+		d,
+		originXPx - originXPx * a - originYPx * c,
+		originYPx - originXPx * b - originYPx * d
+	];
+};
 //#endregion
-export { POINTS_PER_PIXEL, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix };
+export { POINTS_PER_PIXEL, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix, transformMatrix };

package/dist/pdf/paint.js

@@ -1,7 +1,7 @@
 import { STROKE_DASH_FACTORS, glyphCellOffsetsPx } from "../display-list/primitives.js";
 import { needsShaping } from "../shaping/placeRun.js";
 import { TEXT_RENDER_MODE, createContentStream } from "./contentStream.js";
-import { basePageMatrix, rotationMatrix } from "./pageSpace.js";
+import { basePageMatrix, transformMatrix } from "./pageSpace.js";
 import { Result, TaggedError, panic } from "better-result";
 //#region src/pdf/paint.ts
 /**
@@ -358,7 +358,7 @@ const paintPrimitive = (context, primitive) => {
 			return;
 		case "rotateGroup":
 			context.stream.save();
-			context.stream.concat(rotationMatrix(primitive.degrees, primitive.originXPx, primitive.originYPx));
+			context.stream.concat(transformMatrix(primitive));
 			for (const child of primitive.children) paintPrimitive(context, child);
 			context.stream.restore();
 			return;

package/dist/prosemirror/attrs/index.js

@@ -27,6 +27,8 @@ const TEXT_BOX_AUTO_FIT_VALUES = [
 	"shape"
 ];
 const TEXT_BOX_TEXT_WRAP_VALUES = ["square", "none"];
+/** The complete DrawingML transform subset carried by text boxes. */
+const TEXT_BOX_TRANSFORM_PATTERN = /^(?=rotate|scaleX|scaleY)(?:rotate\(-?\d+(?:\.\d+)?deg\)(?: )?)?(?:scaleX\(-1\)(?: )?)?(?:scaleY\(-1\))?$/u;
 const FIELD_KINDS = ["simple", "complex"];
 const MATH_DISPLAYS = ["inline", "block"];
 const SHAPE_FILL_TYPES = [
@@ -168,6 +170,7 @@ const readParagraphAttrs = (node) => {
 	const issues = [];
 	expectNodeType(node, "paragraph", issues);
 	optionalString(attrs, "paraId", "paragraph.attrs.paraId", issues);
+	optionalString(attrs, "_docxParagraphSourceToken", "paragraph.attrs._docxParagraphSourceToken", issues);
 	optionalString(attrs, "textId", "paragraph.attrs.textId", issues);
 	optionalOneOf(attrs, "alignment", "paragraph.attrs.alignment", issues, PARAGRAPH_ALIGNMENT_VALUES);
 	optionalOneOf(attrs, "alignmentFromStyle", "paragraph.attrs.alignmentFromStyle", issues, PARAGRAPH_ALIGNMENT_VALUES);
@@ -367,7 +370,6 @@ const readTableCellAttrs = (node) => {
 	optionalRecord(attrs, "_originalFormatting", "tableCell.attrs._originalFormatting", issues);
 	optionalTableCellRevision(attrs, issues);
 	optionalBoolean(attrs, "_preserveVMergeRestart", "tableCell.attrs._preserveVMergeRestart", issues);
-	optionalArray(attrs, "_docxVMergeContinuationCells", "tableCell.attrs._docxVMergeContinuationCells", issues);
 	return attrsResult(attrs, issues);
 };
 const expectTableCellAttrs = (node) => expectCachedNodeAttrs(node, tableCellAttrsCache, readTableCellAttrs, "table cell attrs");
@@ -520,6 +522,7 @@ const readTextBoxAttrs = (node) => {
 	optionalNumber(attrs, "outlineWidth", "textBox.attrs.outlineWidth", issues);
 	optionalString(attrs, "outlineColor", "textBox.attrs.outlineColor", issues);
 	optionalOneOf(attrs, "outlineStyle", "textBox.attrs.outlineStyle", issues, OUTLINE_STYLE_ATTR_VALUES);
+	optionalTextBoxTransform(attrs, "transform", "textBox.attrs.transform", issues);
 	optionalNumber(attrs, "marginTop", "textBox.attrs.marginTop", issues);
 	optionalNumber(attrs, "marginBottom", "textBox.attrs.marginBottom", issues);
 	optionalNumber(attrs, "marginLeft", "textBox.attrs.marginLeft", issues);
@@ -905,6 +908,21 @@ const optionalString = (attrs, key, path, issues) => {
 		message: "Expected a string."
 	});
 };
+const optionalTextBoxTransform = (attrs, key, path, issues) => {
+	const value = attrs[key];
+	if (value === void 0 || value === null) return;
+	if (typeof value !== "string") {
+		issues.push({
+			path,
+			message: "Expected a string."
+		});
+		return;
+	}
+	if (!TEXT_BOX_TRANSFORM_PATTERN.test(value)) issues.push({
+		path,
+		message: "Expected DrawingML rotation and/or horizontal or vertical flips."
+	});
+};
 const optionalSdtListItems = (attrs, key, path, issues) => {
 	const value = attrs[key];
 	if (value === void 0 || value === null) return;
@@ -1236,13 +1254,6 @@ const optionalAutospacingBase = (attrs, path, issues) => {
 	optionalNumber(value, "before", `${path}.before`, issues);
 	optionalNumber(value, "after", `${path}.after`, issues);
 };
-const optionalArray = (attrs, key, path, issues) => {
-	const value = attrs[key];
-	if (value !== void 0 && value !== null && !Array.isArray(value)) issues.push({
-		path,
-		message: "Expected an array."
-	});
-};
 const optionalBorderMap = (attrs, key, path, issues, sides) => {
 	const value = attrs[key];
 	if (value === void 0 || value === null) return;

package/dist/prosemirror/commands/comments.js

@@ -1,3 +1,4 @@
+import { joinProseParagraphsWithRightPropertySource } from "../../docx/paragraphPropertySource.js";
 import { appendHeadlessInlineResolution } from "../../internal/headlessRevisionResolution.js";
 import { stateAllowsHeadlessRevisionResolution } from "../../internal/headlessRevisionResolutionGuard.js";
 import { expectParagraphAttrs, expectRunPropertyChangeMarkAttrs } from "../attrs/index.js";
@@ -232,15 +233,23 @@ function resolveChange(from, to, mode, revisionIds, execution = "legacy") {
 					tr.setNodeAttribute(mappedPos, "pPrMark", null);
 					continue;
 				}
+				const emptyFirstParagraph = holdsNoContent(paragraph);
 				const joinedAttrs = {
-					...(holdsNoContent(paragraph) ? nextNode : paragraph).attrs,
+					...(emptyFirstParagraph ? nextNode : paragraph).attrs,
 					pPrMark: nextNode.attrs["pPrMark"],
 					sectionBreakType: nextNode.attrs["sectionBreakType"],
 					_sectionProperties: nextNode.attrs["_sectionProperties"]
 				};
 				try {
-					tr.join(joinPos);
-					tr.setNodeMarkup(mappedPos, void 0, joinedAttrs);
+					if (emptyFirstParagraph) joinProseParagraphsWithRightPropertySource({
+						attrs: joinedAttrs,
+						pos: joinPos,
+						transaction: tr
+					});
+					else {
+						tr.join(joinPos);
+						tr.setNodeMarkup(mappedPos, void 0, joinedAttrs);
+					}
 					if (ownsSectionEndpoint(paragraph)) {
 						removedSectionEndpointCount++;
 						removedSectionReferences.push(...sectionReferencesOf(paragraph));

package/dist/prosemirror/commands/tableCellMergeResolution.js

@@ -1,13 +1,17 @@
+import { decodeTableCellParagraphSourcePayload, restoreTableCellsWithParagraphPropertySources, transportTableCellsWithParagraphPropertySources } from "../../docx/paragraphPropertySource.js";
 import { standaloneTableCellFromProseMirror } from "../conversion/fromProseDoc.js";
 import { standaloneTableCellToProseMirror } from "../conversion/toProseDoc.js";
 import { getTableCellMergeChange } from "../tableCellMergeRevision.js";
 import { Result } from "better-result";
 import { TableMap } from "prosemirror-tables";
 //#region src/prosemirror/commands/tableCellMergeResolution.ts
+const tableCellContinuationPayload = (node) => {
+	const value = node.attrs["_docxVMergeContinuationCells"];
+	return value === void 0 || value === null ? null : decodeTableCellParagraphSourcePayload(value);
+};
 const hasMatchingCollapsedTableCellMerge = (node, revisionSet) => {
-	const continuationCells = node.attrs["_docxVMergeContinuationCells"];
-	if (!Array.isArray(continuationCells)) return false;
-	return continuationCells.some((cell) => {
+	const payload = tableCellContinuationPayload(node);
+	return payload !== null && payload.cells.some((cell) => {
 		const change = getTableCellMergeChange(cell);
 		return change !== null && (revisionSet === null || revisionSet.has(change.info.id));
 	});
@@ -71,19 +75,19 @@ const mergeTableCellWithCellAbove = (tr, cellPos) => {
 	if (!aboveCell || typeof aboveRowspan !== "number" || typeof cellRowspan !== "number" || aboveRowspan < 1 || cellRowspan < 1) return false;
 	const continuationCells = tableCellContinuationCells(aboveCell, aboveRowspan);
 	continuationCells.push(tableCellContinuationFromNode(cell));
-	const nestedContinuations = cell.attrs["_docxVMergeContinuationCells"];
-	if (Array.isArray(nestedContinuations)) continuationCells.push(...nestedContinuations);
+	const nestedPayload = tableCellContinuationPayload(cell);
+	if (nestedPayload) continuationCells.push(...nestedPayload.cells);
 	tr.delete(cellPos, cellPos + cell.nodeSize);
 	tr.setNodeMarkup(abovePos, void 0, {
 		...aboveCell.attrs,
 		rowspan: aboveRowspan + cellRowspan,
-		_docxVMergeContinuationCells: continuationCells
+		_docxVMergeContinuationCells: transportTableCellsWithParagraphPropertySources(continuationCells)
 	});
 	return true;
 };
 const tableCellContinuationCells = (cell, rowspan) => {
-	const stored = cell.attrs["_docxVMergeContinuationCells"];
-	const cells = Array.isArray(stored) ? [...stored] : [];
+	const payload = tableCellContinuationPayload(cell);
+	const cells = payload ? [...payload.cells] : [];
 	while (cells.length < rowspan - 1) cells.push(emptyVerticalMergeContinuation());
 	return cells;
 };
@@ -109,8 +113,10 @@ const emptyVerticalMergeContinuation = () => ({
 });
 const resolveCollapsedTableCellMerge = (tr, cellPos, mode, revisionSet) => {
 	const cell = tr.doc.nodeAt(cellPos);
-	const stored = cell?.attrs["_docxVMergeContinuationCells"];
-	if (!cell || !Array.isArray(stored)) return false;
+	if (!cell) return false;
+	const payload = tableCellContinuationPayload(cell);
+	if (!payload) return false;
+	const stored = payload.cells;
 	const matchingIndices = [];
 	const nextCells = stored.map((continuationCell, index) => {
 		const change = getTableCellMergeChange(continuationCell);
@@ -142,8 +148,9 @@ const resolveCollapsedTableCellMerge = (tr, cellPos, mode, revisionSet) => {
 	const rowspan = cell.attrs["rowspan"];
 	if (typeof rowspan !== "number" || rowspan !== stored.length + 1 || rectangle.bottom - rectangle.top !== rowspan) return false;
 	const restorations = [];
+	const restoredCells = restoreTableCellsWithParagraphPropertySources(payload);
 	for (const index of splitIndices) {
-		const source = nextCells[index];
+		const source = restoredCells[index];
 		if (!source) return false;
 		const restoredCell = createRestoredTableCell(cell, source);
 		if (!restoredCell) return false;

package/dist/prosemirror/conversion/fromProseDoc.js

@@ -1,5 +1,5 @@
 import { numPrEqual } from "../../docx/numberingParser.js";
-import { copyParagraphPropertySource, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceTransferId, linkParagraphPropertySourceCandidate, recreateProseNodeWithParagraphPropertySource } from "../../docx/paragraphPropertySource.js";
+import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, ParagraphPropertySourceValidationError, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, linkParagraphPropertySourceCandidate, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings } from "../../docx/paragraphPropertySource.js";
 import { visitDocxParagraphs } from "../../docx/paragraphTraversal.js";
 import { ShapeOutlineStyleSchema, narrowEnum } from "../../docx/parserEnums.js";
 import { DATE_UTC_ATTRIBUTE } from "../../docx/trackedChangeInfo.js";
@@ -103,23 +103,84 @@ const uniqueParagraphsById = (content, includeTransferIds = false) => {
 	});
 	return paragraphs;
 };
+const restoreParagraphPropertySource = (paragraph, baseParagraph) => {
+	copyParagraphPropertySource(paragraph, baseParagraph);
+	const baseFormatting = baseParagraph.formatting;
+	if (!baseFormatting?.numPr || !baseFormatting.numPrFromStyle || !numPrEqual(baseFormatting.numPr, baseFormatting.numPrFromStyle)) return;
+	const { numPr, numPrFromStyle, ...authoredFormatting } = baseFormatting;
+	if (canonicalJson(paragraph.formatting ?? {}) !== canonicalJson(authoredFormatting)) return;
+	paragraph.formatting = {
+		...paragraph.formatting,
+		numPr,
+		numPrFromStyle
+	};
+};
 const restoreParagraphPropertySources = (content, baseContent, linkedTargets, linkedSources) => {
 	const baseParagraphs = uniqueParagraphsById(baseContent, true);
 	for (const [paraId, paragraph] of uniqueParagraphsById(content)) {
 		const baseParagraph = baseParagraphs.get(paraId);
 		if (!paragraph || !baseParagraph || linkedTargets.has(paragraph) || linkedSources.has(baseParagraph) || !getParagraphPropertySource(baseParagraph)) continue;
-		copyParagraphPropertySource(paragraph, baseParagraph);
-		const baseFormatting = baseParagraph.formatting;
-		if (!baseFormatting?.numPr || !baseFormatting.numPrFromStyle || !numPrEqual(baseFormatting.numPr, baseFormatting.numPrFromStyle)) continue;
-		const { numPr, numPrFromStyle, ...authoredFormatting } = baseFormatting;
-		if (canonicalJson(paragraph.formatting ?? {}) !== canonicalJson(authoredFormatting)) continue;
-		paragraph.formatting = {
-			...paragraph.formatting,
-			numPr,
-			numPrFromStyle
-		};
+		restoreParagraphPropertySource(paragraph, baseParagraph);
 	}
 };
+const sourceValidationError = (code, message) => new ParagraphPropertySourceValidationError({
+	code,
+	message
+});
+const validateParagraphPropertySourceTokens = (pmDoc, baseDocument, contract) => {
+	const sourceParagraphs = copyDocumentParagraphPropertySources(baseDocument);
+	if (!sourceParagraphs) panic("A paragraph-property source contract lost its source registry");
+	const currentTokens = /* @__PURE__ */ new Set();
+	visitDocumentStoryParagraphs(baseDocument.package.document.content, (paragraph) => {
+		const token = getParagraphPropertySourceToken(paragraph);
+		if (!token) {
+			if (paragraphPropertySourceBelongsToDocument(paragraph, baseDocument)) throw sourceValidationError("invalid_token", "A source-bound paragraph is missing its paragraph-property token.");
+			return;
+		}
+		if (!paragraphPropertySourceTokenMatchesContract(token, contract)) throw sourceValidationError("invalid_token", "The source document contains an invalid paragraph-property token.");
+		if (!sourceParagraphs.has(token)) throw sourceValidationError("unknown_token", "The source document contains an unknown paragraph-property token.");
+		if (currentTokens.has(token)) throw sourceValidationError("duplicate_token", "The source document contains a duplicate paragraph-property token.");
+		currentTokens.add(token);
+	});
+	const seen = /* @__PURE__ */ new Set();
+	const validateToken = (token) => {
+		if (token === null || token === void 0) return;
+		if (!isParagraphPropertySourceToken(token)) throw sourceValidationError("invalid_token", "A paragraph contains a malformed paragraph-property token.");
+		if (!paragraphPropertySourceTokenMatchesContract(token, contract)) throw sourceValidationError("unknown_token", "A paragraph-property token belongs to a different source document.");
+		if (seen.has(token)) throw sourceValidationError("duplicate_token", "A paragraph-property token is attached to more than one paragraph.");
+		if (!sourceParagraphs.has(token)) throw sourceValidationError("unknown_token", "A paragraph-property token is not present in the source document.");
+		seen.add(token);
+	};
+	const validateTableCellBinding = (binding) => {
+		switch (binding.type) {
+			case "authored": return;
+			case "source":
+				validateToken(binding.token);
+				return;
+			default: return binding;
+		}
+	};
+	pmDoc.descendants((node) => {
+		if (node.type.name === "tableCell" || node.type.name === "tableHeader") {
+			const continuationCells = expectTableCellAttrs(node)._docxVMergeContinuationCells;
+			if (continuationCells !== void 0 && continuationCells !== null) visitTableCellParagraphPropertySourceBindings(decodeTableCellParagraphSourcePayload(continuationCells), (binding) => validateTableCellBinding(binding));
+			return true;
+		}
+		if (node.type.name !== "paragraph") return true;
+		validateToken(getProseParagraphPropertySourceToken(node));
+		return false;
+	});
+	return sourceParagraphs;
+};
+const restoreParagraphPropertySourcesByToken = (content, baseParagraphs) => {
+	visitDocumentStoryParagraphs(content, (paragraph) => {
+		const token = getParagraphPropertySourceToken(paragraph);
+		if (!token) return;
+		const baseParagraph = baseParagraphs.get(token);
+		if (!baseParagraph) panic("Validated paragraph-property token lost its source owner");
+		restoreParagraphPropertySource(paragraph, baseParagraph);
+	});
+};
 const restoreLinkedParagraphPropertySources = (content) => {
 	const targetsBySource = /* @__PURE__ */ new Map();
 	const linkedTargets = /* @__PURE__ */ new Set();
@@ -133,7 +194,7 @@ const restoreLinkedParagraphPropertySources = (content) => {
 	});
 	for (const [source, targets] of targetsBySource) if (targets.length === 1) {
 		const target = targets.at(0);
-		if (target) copyParagraphPropertySource(target, source);
+		if (target) copyParagraphPropertyCapture(target, source);
 	}
 	return {
 		targets: linkedTargets,
@@ -143,20 +204,30 @@ const restoreLinkedParagraphPropertySources = (content) => {
 /** Convert a ProseMirror document to the document model. */
 function fromProseDoc(pmDoc, baseDocument) {
 	assertValidProseMirrorDocument(pmDoc, "Cannot convert invalid ProseMirror document to DOCX model");
+	const baseContract = baseDocument ? getDocumentParagraphPropertySourceContract(baseDocument) : void 0;
+	const proseContractAttribute = pmDoc.attrs[PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR];
+	const proseContract = getProseDocumentParagraphPropertySourceContract(pmDoc);
+	if (proseContractAttribute !== null && proseContractAttribute !== void 0 && proseContract === null || (baseContract ?? null) !== proseContract) throw sourceValidationError("contract_mismatch", "The ProseMirror document does not match its paragraph-property source document.");
+	const tokenSources = baseContract && proseContract && baseDocument ? validateParagraphPropertySourceTokens(pmDoc, baseDocument, baseContract) : null;
 	const blocks = extractBlocks(pmDoc, "resolve", baseDocument?.package.styles ? createStyleEngine(baseDocument.package.styles) : null);
 	const linkedSources = restoreLinkedParagraphPropertySources(blocks);
-	if (baseDocument) restoreParagraphPropertySources(blocks, baseDocument.package.document.content, linkedSources.targets, linkedSources.sources);
+	if (tokenSources) restoreParagraphPropertySourcesByToken(blocks, tokenSources);
+	else if (baseDocument) restoreParagraphPropertySources(blocks, baseDocument.package.document.content, linkedSources.targets, linkedSources.sources);
 	const documentBody = { content: blocks };
 	if (baseDocument?.package.document.finalSectionProperties) documentBody.finalSectionProperties = baseDocument.package.document.finalSectionProperties;
 	if (baseDocument?.package.document.sections) documentBody.sections = baseDocument.package.document.sections;
 	if (baseDocument?.package.document.comments) documentBody.comments = baseDocument.package.document.comments;
-	if (baseDocument) return {
-		...baseDocument,
-		package: {
-			...baseDocument.package,
-			document: documentBody
-		}
-	};
+	if (baseDocument) {
+		const updatedDocument = {
+			...baseDocument,
+			package: {
+				...baseDocument.package,
+				document: documentBody
+			}
+		};
+		copyDocumentParagraphPropertySourceContract(updatedDocument, baseDocument);
+		return updatedDocument;
+	}
 	return { package: { document: documentBody } };
 }
 const isSuggestedMark = (mark) => mark.attrs["provenance"] === "suggested";
@@ -2606,7 +2677,7 @@ function convertPMTableRow(node, documentCounts, activeVerticalMerges, styleReso
 			const colspan = Math.max(cellAttrs.colspan, 1);
 			cells.push(convertPMTableCell(cellNode, documentCounts, styleResolver));
 			if (cellAttrs.rowspan > 1) {
-				const continuationCells = cellAttrs._docxVMergeContinuationCells;
+				const continuationCells = cellAttrs._docxVMergeContinuationCells !== void 0 && cellAttrs._docxVMergeContinuationCells !== null ? restoreTableCellsWithParagraphPropertySources(decodeTableCellParagraphSourcePayload(cellAttrs._docxVMergeContinuationCells)) : void 0;
 				activeVerticalMerges?.set(gridColumn, {
 					remainingRows: cellAttrs.rowspan - 1,
 					colspan,
@@ -2829,6 +2900,8 @@ function convertPMTextBox(node, styleResolver = null) {
 		}
 	};
 	if (attrs.textBoxId) shape.id = attrs.textBoxId;
+	const transform = parseTransformAttr(attrs.transform);
+	if (transform) shape.transform = transform;
 	if (attrs.fillColor) shape.fill = {
 		type: "solid",
 		color: { rgb: attrs.fillColor.replace("#", "") }