@stll/folio-core 0.33.1 → 0.34.0

package/dist/ai-edits/apply.d.ts

@@ -1,3 +1,4 @@
+import { FolioTableTemplates } from "./table-template.js";
 import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
 import { WordDiffGranularity } from "./word-diff.js";
 import { EditorState, Transaction } from "prosemirror-state";
@@ -42,6 +43,20 @@ type ApplyFolioAIEditOperationsOptions = {
   revisionStamp?: FolioRevisionStamp;
   /** How a replacement's redline is cut. */
   wordDiff?: FolioWordDiffOptions;
+  /**
+   * Tables and rows an `insertTable` / `insertTableRow` operation should place
+   * verbatim, by operation id.
+   *
+   * The operations describe their content as cell texts, which is what a
+   * caller writing a table from nothing has. A caller copying one it already
+   * holds — a comparison placing the target document's table — has the whole
+   * thing: `w:tblPr`, the `w:tblGrid` widths, `w:trPr`, `w:tcPr` with its
+   * spans and merges, and cell paragraphs with their own properties. Rebuilt
+   * from text, none of that survives. Kept out of the operation payload
+   * because it is a document node rather than JSON: the serialized contract
+   * still describes a table by its cell texts.
+   */
+  tableTemplates?: FolioTableTemplates;
 };
 /**
  * How an apply batch cuts the redline for a replacement. Word-level by

package/dist/ai-edits/apply.js

@@ -1,5 +1,6 @@
-import { expectParagraphAttrs, expectRunPropertyChangeMarkAttrs } from "../prosemirror/attrs/index.js";
+import { expectParagraphAttrs, expectRunFormattingOverrideMarkAttrs, expectRunPropertyChangeMarkAttrs } from "../prosemirror/attrs/index.js";
 import { PPR_CHANGE_SCOPED_ATTR_KEYS } from "../prosemirror/commands/propertyChangeScope.js";
+import { addedBreakCarrierBefore, finalParagraphsOf, paragraphEndsItsContainer } from "../prosemirror/containerFinalParagraph.js";
 import { marksToTextFormatting } from "../prosemirror/conversion/fromProseDoc.js";
 import { requestDeterministicParaIds } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
 import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
@@ -11,8 +12,9 @@ import { hasInlineEmphasis, parseInlineEmphasisRuns, stripInlineEmphasisMarkers
 import { hashFolioAIBlockText, isHiddenTableRow, normalizeFolioAIBlockText } from "./snapshot.js";
 import { mergeTableRectangle, mergeTrackedVerticalTableCells, splitTableRectangle, splitTrackedVerticalTableCell } from "./table-cell-mutations.js";
 import { planTableMutations } from "./table-mutation-plan.js";
-import { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, splitCellParagraphTexts } from "./table-row-column-mutations.js";
+import { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts } from "./table-row-column-mutations.js";
 import { findEnclosingTableCell, findEnclosingTableRow, findOutermostTableBoundary, tableRectangleCutsMergedCell } from "./table-targets.js";
+import { tableFromTemplate } from "./table-template.js";
 import { diffWordSegments } from "./word-diff.js";
 import { panic } from "better-result";
 import { TableMap } from "prosemirror-tables";
@@ -152,24 +154,132 @@ const REPLACEMENT_BACKGROUND_CLEAR_FORMATTING = {
 	highlight: false,
 	runShading: false
 };
-const applyInlineFormatting = ({ tr, schema, from, to, formatting }) => {
-	for (const [name, enabled] of Object.entries(formatting)) {
-		const markType = schema.marks[name];
+const INLINE_FORMATTING_MARK_NAMES = {
+	bold: "bold",
+	italic: "italic",
+	underline: "underline",
+	strike: "strike",
+	fontFamily: "fontFamily",
+	fontSizePt: "fontSize",
+	color: "textColor",
+	highlight: "highlight",
+	runShading: "runShading"
+};
+const DIRECT_FONT_PROPERTIES = [
+	"fontFamily",
+	"fontSize",
+	"color"
+];
+const formattingMarkName = (property) => {
+	if (!Object.hasOwn(INLINE_FORMATTING_MARK_NAMES, property)) return null;
+	const name = Reflect.get(INLINE_FORMATTING_MARK_NAMES, property);
+	return typeof name === "string" ? name : null;
+};
+const formattingMarkAttrs = (property, value) => {
+	switch (property) {
+		case "underline": return { style: "single" };
+		case "fontFamily": return typeof value === "string" ? {
+			ascii: value,
+			hAnsi: value
+		} : null;
+		case "fontSizePt": return typeof value === "number" ? { size: value * 2 } : null;
+		case "color": return typeof value === "string" ? { rgb: value.replace(/^#/u, "").toUpperCase() } : null;
+		default: return {};
+	}
+};
+const applyInlineFormatting = ({ tr, schema, from, to, formatting, includedProperties }) => {
+	for (const [property, value] of Object.entries(formatting)) {
+		if (includedProperties && !includedProperties.includes(property)) continue;
+		const markName = formattingMarkName(property);
+		const markType = markName ? schema.marks[markName] : void 0;
 		if (!markType) continue;
-		if (enabled) {
-			tr.addMark(from, to, name === "underline" ? markType.create({ style: "single" }) : markType.create());
+		if (value !== false && value !== null) {
+			const attrs = formattingMarkAttrs(property, value);
+			if (attrs) tr.addMark(from, to, markType.create(attrs));
 			continue;
 		}
 		tr.removeMark(from, to, markType);
 	}
+	applyDirectFontProvenance({
+		tr,
+		schema,
+		from,
+		to,
+		formatting,
+		...includedProperties ? { includedProperties } : {}
+	});
 	return tr;
 };
-const formattingWouldChange = (marks, formatting) => Object.entries(formatting).some(([name, enabled]) => {
-	const mark = marks.find((candidate) => candidate.type.name === name);
-	if (!enabled) return mark !== void 0;
-	if (name === "underline") return mark?.attrs["style"] !== "single";
+const applyDirectFontProvenance = ({ tr, schema, from, to, formatting, includedProperties }) => {
+	if ("highlight" in formatting) return;
+	const changed = [
+		[
+			"fontFamily",
+			"fontFamily",
+			formatting.fontFamily
+		],
+		[
+			"fontSize",
+			"fontSizePt",
+			formatting.fontSizePt
+		],
+		[
+			"color",
+			"color",
+			formatting.color
+		]
+	].filter(([, inputProperty, value]) => value !== void 0 && (!includedProperties || includedProperties.includes(inputProperty)));
+	const markType = schema.marks["runFormattingOverride"];
+	if (!markType || changed.length === 0) return;
+	tr.doc.nodesBetween(from, to, (node, pos) => {
+		if (!node.isText) return;
+		const segmentFrom = Math.max(from, pos);
+		const segmentTo = Math.min(to, pos + node.nodeSize);
+		const existing = node.marks.find((mark) => mark.type === markType);
+		const attrs = existing ? expectRunFormattingOverrideMarkAttrs(existing) : {};
+		const directFontProperties = new Set(attrs.directFontProperties);
+		for (const [property, , value] of changed) if (value === null) directFontProperties.delete(property);
+		else directFontProperties.add(property);
+		tr.removeMark(segmentFrom, segmentTo, markType);
+		const nextAttrs = {
+			...attrs,
+			directFontProperties: DIRECT_FONT_PROPERTIES.filter((property) => directFontProperties.has(property))
+		};
+		if (Object.entries(nextAttrs).some(([key, value]) => key === "directFontProperties" ? Array.isArray(value) && value.length > 0 : value !== null && value !== void 0)) tr.addMark(segmentFrom, segmentTo, markType.create(nextAttrs));
+	});
+};
+const directFontPropertyForFormattingProperty = (property) => {
+	switch (property) {
+		case "fontFamily": return "fontFamily";
+		case "fontSizePt": return "fontSize";
+		case "color": return "color";
+		default: return null;
+	}
+};
+const formattingPropertyWouldChange = (marks, property, value) => {
+	const markName = formattingMarkName(property);
+	const mark = marks.find((candidate) => candidate.type.name === markName);
+	const directFontProperty = directFontPropertyForFormattingProperty(property);
+	if (directFontProperty) {
+		const overrideMark = marks.find((candidate) => candidate.type.name === "runFormattingOverride");
+		const isDirect = overrideMark ? (expectRunFormattingOverrideMarkAttrs(overrideMark).directFontProperties ?? []).includes(directFontProperty) : false;
+		if (value === false || value === null) return isDirect;
+		if (!isDirect) return true;
+	} else if (value === false || value === null) return mark !== void 0;
+	if (property === "underline") return mark?.attrs["style"] !== "single";
+	if (property === "fontFamily") return mark?.attrs["ascii"] !== value || mark?.attrs["hAnsi"] !== value;
+	if (property === "fontSizePt") return Number(mark?.attrs["size"]) !== Number(value) * 2;
+	if (property === "color") {
+		const current = mark?.attrs["rgb"];
+		return (typeof current === "string" ? current.replace(/^#/u, "").toUpperCase() : null) !== String(value).replace(/^#/u, "").toUpperCase();
+	}
 	return mark === void 0;
-});
+};
+const formattingChangesForMarks = (marks, formatting) => {
+	const changes = [];
+	for (const [property, value] of Object.entries(formatting)) if (formattingPropertyWouldChange(marks, property, value)) changes.push(property);
+	return changes;
+};
 const clearReplacementBackground = ({ tr, schema, from, to, mode, revisionId, author, date, initials, suggestionId = null }) => {
 	if (![schema.marks["highlight"], schema.marks["runShading"]].some((markType) => markType !== void 0 && tr.doc.rangeHasMark(from, to, markType))) return tr;
 	if (mode === "direct") return applyInlineFormatting({
@@ -198,7 +308,9 @@ const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, r
 	if (!propertyChangeType) return tr;
 	const segments = [];
 	doc.nodesBetween(from, to, (node, pos) => {
-		if (!node.isText || !formattingWouldChange(node.marks, formatting)) return;
+		if (!node.isText) return;
+		const includedProperties = formattingChangesForMarks(node.marks, formatting);
+		if (includedProperties.length === 0) return;
 		const segmentFrom = Math.max(from, pos);
 		const segmentTo = Math.min(to, pos + node.nodeSize);
 		const previousFormatting = marksToTextFormatting(node.marks);
@@ -217,6 +329,7 @@ const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, r
 		segments.push({
 			from: segmentFrom,
 			to: segmentTo,
+			includedProperties,
 			changes: [...existingChanges, change]
 		});
 	});
@@ -225,17 +338,20 @@ const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, r
 		provenance: "suggested",
 		suggestionId
 	};
-	applyInlineFormatting({
-		tr,
-		schema,
-		from,
-		to,
-		formatting
-	});
-	for (const segment of segments) tr.addMark(segment.from, segment.to, propertyChangeType.create({
-		changes: segment.changes,
-		...suggestionAttrs
-	}));
+	for (const segment of segments) {
+		applyInlineFormatting({
+			tr,
+			schema,
+			from: segment.from,
+			to: segment.to,
+			formatting,
+			includedProperties: segment.includedProperties
+		});
+		tr.addMark(segment.from, segment.to, propertyChangeType.create({
+			changes: segment.changes,
+			...suggestionAttrs
+		}));
+	}
 	return tr;
 };
 /**
@@ -364,9 +480,11 @@ const ordinalAmongSameHash = (snapshot, blockId) => {
 const SIGNATURE_LINE = "_".repeat(28);
 /**
 * A plain table from a grid of cell texts, `null` when the schema has no
-* tables. In tracked mode every row carries `trIns`, which is how Word says
-* "this table is new": there is no whole-table insertion element, only rows
-* that were inserted.
+* tables. In tracked mode every row carries `trIns` and every run inside it
+* carries `w:ins`, which is how the format says "this table is new": there is
+* no whole-table insertion element, only rows that were inserted, and a
+* consumer that reads only run-level revisions keeps the text of a rejected
+* insertion when the row marker stands alone.
 */
 const buildTableNode = ({ schema, rows, revision }) => {
 	const paragraphType = schema.nodes["paragraph"];
@@ -374,7 +492,16 @@ const buildTableNode = ({ schema, rows, revision }) => {
 	const rowType = schema.nodes["tableRow"];
 	const tableType = schema.nodes["table"];
 	if (!paragraphType || !cellType || !rowType || !tableType || rows.length === 0) return null;
-	const rowNodes = rows.map((cells) => rowType.create(revision ? { trIns: revision } : null, cells.map((text) => cellType.create(null, splitCellParagraphTexts(text).map((line) => paragraphType.create(null, line.length > 0 ? schema.text(line) : null))))));
+	const insertionType = schema.marks["insertion"];
+	const marks = revision && insertionType ? [insertionType.create({
+		revisionId: revision.revisionId,
+		author: revision.author,
+		date: revision.date,
+		...revision.initials != null && { initials: revision.initials },
+		...revision.provenance != null && { provenance: revision.provenance },
+		...revision.suggestionId != null && { suggestionId: revision.suggestionId }
+	})] : void 0;
+	const rowNodes = rows.map((cells) => rowType.create(revision ? { trIns: revision } : null, cells.map((text) => cellType.create(null, splitCellParagraphTexts(text).map((line) => paragraphType.create(null, line.length > 0 ? schema.text(line, marks) : null))))));
 	return tableType.create(null, rowNodes);
 };
 /**
@@ -468,6 +595,75 @@ const isBatchableParagraphInsertion = (item, mode) => {
 	const isEmptyInsert = insertTexts.length === 1 && insertTexts[0]?.length === 0;
 	return !(mode === "tracked-changes" && item.operation.pageBreakBefore === true && isEmptyInsert);
 };
+/**
+* Move an ADDED paragraph break off every paragraph its container ends with.
+*
+* A container's final mark carries no revision in either direction: nothing
+* follows it, so "join this paragraph with the one after it" and its mirror
+* both state an edit that cannot be carried out, and a reader is left with a
+* revision neither accepting nor rejecting everything can clear.
+*
+* Appending at a container's end therefore rotates exactly as removing from it
+* does. The break that was added sits between the paragraph the run was
+* appended after and the first appended one, so THAT paragraph's mark is the
+* inserted one, each appended paragraph but the last keeps an inserted mark of
+* its own, and the paragraph the container now ends with takes the free mark
+* the run was appended after. Only which paragraph is left markless changes.
+*
+* A paragraph's properties live on its mark, so the paragraph that inherits
+* the free one records the other's as `w:pPrChange` — what a rejection reads
+* to put the container's ending back the way it was.
+*
+* This runs once over the finished document rather than at each insertion:
+* which paragraph ends a container is only settled when the batch is, and an
+* insertion that looked final was undone by the next operation writing a table
+* after it.
+*/
+const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, author, date, initials }) => {
+	const paragraphTypeName = tr.doc.type.schema.nodes["paragraph"]?.name ?? "paragraph";
+	const rotations = finalParagraphsOf(tr.doc, paragraphTypeName).filter(({ node }) => {
+		const mark = node.attrs["pPrMark"];
+		if (typeof mark !== "object" || mark === null || !("kind" in mark)) return false;
+		if (mark.kind !== "ins" && mark.kind !== "moveTo") return false;
+		const info = "info" in mark ? mark.info : void 0;
+		const revisionId = typeof info === "object" && info !== null && "id" in info ? info.id : void 0;
+		return typeof revisionId === "number" && batchRevisionIds.has(revisionId);
+	});
+	let next = tr;
+	let nextRevisionId = revisionSeed;
+	for (const { position: finalPosition, node: final } of rotations) {
+		const carrier = addedBreakCarrierBefore(next.doc.resolve(finalPosition), final.type.name);
+		if (!carrier) {
+			next = next.setNodeAttribute(finalPosition, "pPrMark", null);
+			continue;
+		}
+		next = next.setNodeAttribute(carrier.position, "pPrMark", final.attrs["pPrMark"]);
+		const previousFormatting = paragraphPropertiesSnapshot(carrier.node);
+		if (JSON.stringify(previousFormatting) === JSON.stringify(paragraphPropertiesSnapshot(final))) {
+			next = next.setNodeAttribute(finalPosition, "pPrMark", null);
+			continue;
+		}
+		const existing = expectParagraphAttrs(final)._propertyChanges;
+		next = next.setNodeMarkup(finalPosition, void 0, {
+			...final.attrs,
+			pPrMark: null,
+			_propertyChanges: [...Array.isArray(existing) ? existing : [], {
+				type: "paragraphPropertyChange",
+				info: {
+					id: nextRevisionId++,
+					author,
+					date,
+					...initials ? { initials } : {}
+				},
+				previousFormatting
+			}]
+		});
+	}
+	return {
+		transaction: next,
+		nextRevisionId
+	};
+};
 const buildInsertedParagraphs = ({ item, schema, mode, author, date, initials, commentMark, suggestionId, revisionSeed, isPairedMove }) => {
 	const operation = item.operation;
 	if (operation.type !== "insertAfterBlock" && operation.type !== "insertBeforeBlock") panic("Only paragraph insertions can build inserted paragraphs", { type: operation.type });
@@ -551,7 +747,7 @@ const buildInsertedParagraphs = ({ item, schema, mode, author, date, initials, c
 		nextRevisionId
 	};
 };
-const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode = "tracked-changes", author = "AI", initials, createCommentId, revisionStamp, revisionIdSeed, wordDiff }) => {
+const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode = "tracked-changes", author = "AI", initials, createCommentId, revisionStamp, revisionIdSeed, wordDiff, tableTemplates }) => {
 	const applied = [];
 	const skipped = [];
 	const normalizations = [];
@@ -978,11 +1174,13 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					continue;
 				}
 				const revision = structuralRevision;
+				const template = tableTemplates?.get(item.operation.id);
 				const result = applyTableRowInsertion({
 					tr,
 					insertion,
 					cellTexts: item.operation.cellTexts,
-					revision
+					revision,
+					...template !== void 0 && { template }
 				});
 				if (result.type === "unsupported") {
 					skipped.push({
@@ -1172,7 +1370,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 			case "deleteBlock":
 				if (mode === "direct") {
 					const at = tr.doc.resolve(item.blockFrom);
-					tr = !(at.index() === at.parent.childCount - 1) || at.nodeBefore?.type.name === item.blockNode.type.name ? tr.delete(item.blockFrom, item.blockTo) : tr.delete(item.blockFrom + 1, item.blockTo - 1);
+					tr = !paragraphEndsItsContainer(at, item.blockNode.type.name) || at.nodeBefore?.type.name === item.blockNode.type.name ? tr.delete(item.blockFrom, item.blockTo) : tr.delete(item.blockFrom + 1, item.blockTo - 1);
 					break;
 				}
 				if (deletionType) {
@@ -1190,8 +1388,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					const inlineRevisionApplied = item.from < item.to || atomRanges.length > 0;
 					appliedRevisionIds = inlineRevisionApplied ? [revisionId] : [];
 					const markPosition = tr.mapping.map(item.blockFrom);
-					const markPlace = tr.doc.resolve(markPosition);
-					if (!(markPlace.index() === markPlace.parent.childCount - 1) && tr.doc.nodeAt(markPosition)?.attrs["pPrMark"] == null) {
+					if (!paragraphEndsItsContainer(tr.doc.resolve(markPosition), item.blockNode.type.name) && tr.doc.nodeAt(markPosition)?.attrs["pPrMark"] == null) {
 						const markRevisionId = revisionSeed++;
 						tr = tr.setNodeAttribute(markPosition, "pPrMark", {
 							kind: isPairedMove(item.operation.moveId) ? "moveFrom" : "del",
@@ -1208,15 +1405,21 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 				if (commentMark) tr = tr.addMark(item.from, item.to, commentMark);
 				break;
 			case "insertTable": {
-				const table = buildTableNode({
+				const revision = {
+					revisionId: revisionSeed,
+					author,
+					date,
+					...trackedRevisionExtras
+				};
+				const template = tableTemplates?.get(item.operation.id);
+				const table = (template === void 0 ? null : tableFromTemplate({
+					schema: view.state.schema,
+					template,
+					...producesTrackedChanges && { revision }
+				})) ?? buildTableNode({
 					schema: view.state.schema,
 					rows: item.operation.rows,
-					...producesTrackedChanges && { revision: {
-						revisionId: revisionSeed,
-						author,
-						date,
-						...trackedRevisionExtras
-					} }
+					...producesTrackedChanges && { revision }
 				});
 				if (!table) {
 					skipped.push({
@@ -1281,13 +1484,23 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					});
 					continue;
 				}
-				for (const rowPosition of rowPositions.toReversed()) tr = tr.setNodeAttribute(rowPosition, "trDel", revision);
+				for (const rowPosition of rowPositions.toReversed()) {
+					tr = tr.setNodeAttribute(rowPosition, "trDel", revision);
+					markTableRowContent({
+						tr,
+						rowPosition,
+						kind: "deletion",
+						revision
+					});
+				}
 				appliedRevisionIds = [revision.revisionId];
 				markStructuralChange(tr);
 				break;
 			}
 			case "setBlockParagraphProperties": {
-				const patch = paragraphPropertiesPatch(item.blockNode, item.operation.properties);
+				const blockPosition = tr.mapping.map(item.blockFrom);
+				const liveBlock = tr.doc.nodeAt(blockPosition) ?? item.blockNode;
+				const patch = paragraphPropertiesPatch(liveBlock, item.operation.properties);
 				if (patch === null) {
 					skipped.push({
 						id: item.operation.id,
@@ -1296,8 +1509,8 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					continue;
 				}
 				if (mode === "direct") {
-					tr = tr.setNodeMarkup(item.blockFrom, void 0, {
-						...item.blockNode.attrs,
+					tr = tr.setNodeMarkup(blockPosition, void 0, {
+						...liveBlock.attrs,
 						...patch
 					});
 					break;
@@ -1311,11 +1524,11 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 						date,
 						...initials ? { initials } : {}
 					},
-					previousFormatting: paragraphPropertiesSnapshot(item.blockNode)
+					previousFormatting: paragraphPropertiesSnapshot(liveBlock)
 				};
-				const existing = expectParagraphAttrs(item.blockNode)._propertyChanges;
-				tr = tr.setNodeMarkup(item.blockFrom, void 0, {
-					...item.blockNode.attrs,
+				const existing = expectParagraphAttrs(liveBlock)._propertyChanges;
+				tr = tr.setNodeMarkup(blockPosition, void 0, {
+					...liveBlock.attrs,
 					...patch,
 					_propertyChanges: [...Array.isArray(existing) ? existing : [], change]
 				});
@@ -1410,6 +1623,16 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 	if (tr.docChanged) {
 		const batchRevisionIds = new Set(applied.flatMap(({ revisionIds }) => revisionIds ?? []));
 		tr = withoutRevisionsOnZeroWidthAnchors(tr, batchRevisionIds);
+		const rotated = withRotatedAddedFinalBreaks({
+			tr,
+			batchRevisionIds,
+			revisionSeed,
+			author,
+			date,
+			initials
+		});
+		tr = rotated.transaction;
+		revisionSeed = rotated.nextRevisionId;
 		if (revisionStamp) requestDeterministicParaIds(tr, `${revisionStamp.date}:${String(revisionStamp.idSeed)}`);
 		view.dispatch(tr);
 	}

package/dist/ai-edits/headless.d.ts

@@ -1,8 +1,12 @@
+import { document_d_exports } from "../types/document.js";
+import { FolioTableTemplates } from "./table-template.js";
 import { FolioAIBlock, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
 import { FolioRevisionStamp, FolioWordDiffOptions } from "./apply.js";
-import { document_d_exports } from "../types/document.js";
 import { FolioDocumentOperationBatch, FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult } from "../document-operations.js";
 import { FolioReviewChange, FolioReviewChangeKind } from "./read.js";
+import { FolioStoryTable } from "./snapshot.js";
+import { TableGeometryPairing } from "./table-geometry.js";
+import { Node } from "prosemirror-model";
 //#region src/ai-edits/headless.d.ts
 /** Options for {@link FolioDocxReviewer.fromBuffer}. */
 type FolioDocxReviewerOptions = {
@@ -76,6 +80,15 @@ type FolioReadReviewedStoryOptions = {
   story?: FolioEditableDocumentStoryHandle;
   view?: FolioReviewedView;
 };
+/** What {@link FolioDocxReviewer.matchStoryTableGeometry} needs to move a table's properties. */
+type FolioMatchStoryTableGeometryOptions = {
+  story?: FolioEditableDocumentStoryHandle;
+  /** The other document's tables, by the index its snapshot numbers them with. */
+  targetTables: ReadonlyMap<number, Node>;
+  /** Base cells and the target cells they were aligned with. */
+  pairings: readonly TableGeometryPairing[];
+  revisionStamp: FolioRevisionStamp;
+};
 type FolioResolveReviewedStoryOptions = {
   story?: FolioEditableDocumentStoryHandle;
   view: FolioResolvedReviewedView;
@@ -100,6 +113,14 @@ declare class FolioDocumentStoryNotFoundError extends FolioDocumentStoryNotFound
 type FolioApplyDocumentOperationsToStoryOptions = FolioApplyDocumentOperationsOptions & {
   story: FolioEditableDocumentStoryHandle;
   batch: FolioDocumentOperationBatch;
+  /**
+   * Tables and rows an `insertTable` / `insertTableRow` in the batch places
+   * verbatim, by operation id. A caller copying a table it already holds —
+   * `compareDocx` placing the target document's table — hands it over whole
+   * instead of letting the operation rebuild it from its cell texts and lose
+   * every table, row and cell property on the way.
+   */
+  tableTemplates?: FolioTableTemplates;
 };
 declare const isFolioReviewedView: (value: unknown) => value is FolioReviewedView;
 declare const isFolioResolvedReviewedView: (value: unknown) => value is FolioResolvedReviewedView;
@@ -201,6 +222,29 @@ declare class FolioDocxReviewer {
   getDocumentProperties(): Readonly<NonNullable<document_d_exports.Document["package"]["properties"]>> | null;
   /** Snapshot one editable story into stable, operation-ready blocks. */
   snapshotStory(story: FolioEditableDocumentStoryHandle): FolioAIEditSnapshot | null;
+  /**
+   * One story's tables, in the document order {@link snapshotStory} numbers
+   * them with, read through a reviewed view.
+   *
+   * A block snapshot says which table a paragraph sits in and nothing about
+   * the table itself. A caller that has to reproduce one — a comparison
+   * copying the target's table into the base, or checking that accepting its
+   * own redline reproduced it — needs the node: its `w:tblPr`, its `w:tblGrid`
+   * widths, and every row's and cell's properties.
+   */
+  storyTables({ story, view }?: FolioReadReviewedStoryOptions): readonly FolioStoryTable[];
+  /**
+   * Move the paired tables' own properties onto this story's tables, as
+   * tracked property changes.
+   *
+   * `w:tblPr`, `w:trPr` and `w:tcPr` belong to no block, so no block operation
+   * can carry them: a table that stayed in place while its widths, shading,
+   * borders or header row changed reads as unedited. Each difference is
+   * written as the target's property set plus a `w:tblPrChange` /
+   * `w:trPrChange` / `w:tcPrChange` holding the previous one, which is what a
+   * reject restores. A set that already agrees produces no revision.
+   */
+  matchStoryTableGeometry({ story, targetTables, pairings, revisionStamp }: FolioMatchStoryTableGeometryOptions): number;
   /** Read one story through an immutable reviewed-view projection. */
   readReviewedStory(options?: FolioReadReviewedStoryOptions): FolioReviewedStory | null;
   /** Resolve one editable story to its original or final state. */
@@ -219,7 +263,7 @@ declare class FolioDocxReviewer {
    */
   applyDocumentOperations(batch: FolioDocumentOperationBatch, options?: FolioApplyDocumentOperationsOptions): FolioDocumentOperationResult;
   /** Apply a versioned operation batch to one editable document story. */
-  applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff }: FolioApplyDocumentOperationsToStoryOptions): FolioDocumentOperationResult;
+  applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff, tableTemplates }: FolioApplyDocumentOperationsToStoryOptions): FolioDocumentOperationResult;
   private applyDocumentOperationsInternal;
   /** Undo the latest unchanged document-operation batch and its created comments. */
   undoDocumentOperations(undoHandle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
@@ -382,4 +426,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };

package/dist/ai-edits/headless.js

@@ -14,7 +14,8 @@ import { schema, singletonManager } from "../prosemirror/schema/index.js";
 import { deterministicHexId } from "../utils/hexId.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
 import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
-import { createFolioAIEditSnapshot, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./snapshot.js";
+import { createFolioAIEditSnapshot, folioStoryTables, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./snapshot.js";
+import { matchTableGeometry } from "./table-geometry.js";
 import { TaggedError } from "better-result";
 import { Fragment } from "prosemirror-model";
 import { EditorState } from "prosemirror-state";
@@ -314,6 +315,53 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		const state = this.getEditableStoryState(story);
 		return state ? createFolioAIEditSnapshot(state.doc) : null;
 	}
+	/**
+	* One story's tables, in the document order {@link snapshotStory} numbers
+	* them with, read through a reviewed view.
+	*
+	* A block snapshot says which table a paragraph sits in and nothing about
+	* the table itself. A caller that has to reproduce one — a comparison
+	* copying the target's table into the base, or checking that accepting its
+	* own redline reproduced it — needs the node: its `w:tblPr`, its `w:tblGrid`
+	* widths, and every row's and cell's properties.
+	*/
+	storyTables({ story = MAIN_STORY, view = "final" } = {}) {
+		if (!isFolioReviewedView(view)) throw new UnsupportedFolioReviewedViewError({
+			message: "Unsupported reviewed document view.",
+			receivedView: view
+		});
+		const sourceState = this.getEditableStoryState(story);
+		return sourceState ? folioStoryTables(resolveReviewedState(sourceState, view).doc) : [];
+	}
+	/**
+	* Move the paired tables' own properties onto this story's tables, as
+	* tracked property changes.
+	*
+	* `w:tblPr`, `w:trPr` and `w:tcPr` belong to no block, so no block operation
+	* can carry them: a table that stayed in place while its widths, shading,
+	* borders or header row changed reads as unedited. Each difference is
+	* written as the target's property set plus a `w:tblPrChange` /
+	* `w:trPrChange` / `w:tcPrChange` holding the previous one, which is what a
+	* reject restores. A set that already agrees produces no revision.
+	*/
+	matchStoryTableGeometry({ story = MAIN_STORY, targetTables, pairings, revisionStamp }) {
+		const state = this.getEditableStoryState(story);
+		if (!state || pairings.length === 0) return revisionStamp.idSeed;
+		const transaction = state.tr;
+		const { nextRevisionId } = matchTableGeometry({
+			tr: transaction,
+			baseTables: folioStoryTables(state.doc),
+			targetTables,
+			pairings,
+			revision: {
+				author: this.author,
+				date: revisionStamp.date,
+				idSeed: revisionStamp.idSeed
+			}
+		});
+		if (transaction.docChanged) this.setEditableStoryState(story, state.apply(transaction));
+		return nextRevisionId;
+	}
 	/** Read one story through an immutable reviewed-view projection. */
 	readReviewedStory(options = {}) {
 		const story = options.story ?? MAIN_STORY;
@@ -388,17 +436,18 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 	}
 	/** Apply a versioned operation batch to one editable document story. */
-	applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff }) {
+	applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff, tableTemplates }) {
 		return this.applyDocumentOperationsInternal({
 			story,
 			batch,
 			...snapshot !== void 0 && { snapshot },
 			...revisionStamp !== void 0 && { revisionStamp },
 			...wordDiff !== void 0 && { wordDiff },
+			...tableTemplates !== void 0 && { tableTemplates },
 			createUndoEntry: true
 		});
 	}
-	applyDocumentOperationsInternal({ story, batch, snapshot, revisionStamp, wordDiff, createUndoEntry }) {
+	applyDocumentOperationsInternal({ story, batch, snapshot, revisionStamp, wordDiff, tableTemplates, createUndoEntry }) {
 		const beforeState = this.requireEditableStoryState(story);
 		const createdCommentsLengthBefore = this.createdComments.length;
 		const view = {
@@ -415,6 +464,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			author: this.author,
 			...revisionStamp !== void 0 && { revisionStamp },
 			...wordDiff !== void 0 && { wordDiff },
+			...tableTemplates !== void 0 && { tableTemplates },
 			createCommentId: (text) => {
 				const comment = createReviewerComment(this.nextCommentId(), text, this.author);
 				this.createdComments.push(comment);