@stll/folio-core 0.36.0 → 0.37.1

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

@@ -1,21 +1,26 @@
 import { document_d_exports } from "../types/document.js";
+import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
 //#region src/ai-edits/types.d.ts
 type FolioAIBlockKind = "heading" | "listItem" | "paragraph";
-type FolioAIInlineFormatting = Partial<Record<"bold" | "italic" | "underline" | "strike", boolean>> & {
-  fontFamily?: string | null;
-  fontSizePt?: number | null;
-  color?: string | null;
-};
-type FolioAIBlockPreviewRun = {
-  text: string;
-  bold?: boolean;
-  italic?: boolean;
-  underline?: boolean;
-  strike?: boolean;
-  fontFamily?: string;
-  fontSizePt?: number;
-  color?: string;
-  directFormatting?: FolioAIInlineFormatting;
+/** Boolean run properties supported by snapshots and range-formatting mutations. */
+type FolioAIInlineBooleanProperty = FolioContentInlineBooleanProperty;
+type FolioAIInlineFormatting = FolioContentInlineFormatting;
+/**
+ * A run-formatting mutation: `false` authors an explicit off value, while
+ * `null` removes the direct property so its inherited value becomes effective.
+ */
+type FolioAIInlineFormattingPatch = FolioContentInlineFormattingPatch;
+type FolioAIBlockPreviewRun = FolioContentRun;
+/**
+ * A zero-width inline structure at one clean-text boundary. `pageBreak`
+ * always represents an authored `<w:br w:type="page"/>`; an omitted `clear`
+ * remains distinct from any explicit value even though it does not affect
+ * layout for this break type.
+ */
+type FolioAIBlockStructuralBoundary = {
+  type: "pageBreak";
+  offset: number;
+  clear?: document_d_exports.BreakContent["clear"];
 };
 /**
  * Where a block sits inside its innermost enclosing table. Every index is
@@ -25,45 +30,16 @@ type FolioAIBlockPreviewRun = {
  * not a grid column), and `paragraphIndex` orders the block among the cell's
  * own blocks. Absent on a block that is not inside a table.
  */
-type FolioAIBlockTableLocation = {
-  /**
-   * Document-order index of the OUTERMOST table the block sits in — the same
-   * as `tableIndex` unless tables nest. A comparison aligns on this: a table
-   * inside a cell is part of its parent, not a structure of its own that can
-   * be paired against one somewhere else.
-   */
-  outerTableIndex: number;
-  tableIndex: number;
-  rowIndex: number;
-  cellIndex: number;
-  /** Grid column occupied by the cell's left edge, derived from `TableMap`. */
-  gridColumnIndex: number;
-  /** Number of grid columns occupied by this physical cell. */
-  columnSpan: number;
-  /** Number of grid rows occupied by this physical cell. */
-  rowSpan: number;
-  paragraphIndex: number;
-};
-type FolioAIBlock = {
-  id: string;
-  kind: FolioAIBlockKind;
-  text: string;
-  /** One-based heading depth when the block has outline semantics. */
-  headingLevel?: number;
-  displayLabel?: string;
-  styleId?: string;
-  /** Direct `w:pPr/w:jc`; absent when alignment comes only from a style. */
-  directAlignment?: document_d_exports.ParagraphAlignment;
-  /**
-   * `w:numPr/w:ilvl`: the block's list indent level. Present only on a block
-   * that carries numbering, and the only pPr property a redline can move
-   * without touching a word — a demoted list item reads as unchanged text and
-   * is not.
-   */
-  listLevel?: number;
-  previewRuns?: FolioAIBlockPreviewRun[];
-  table?: FolioAIBlockTableLocation;
+type FolioAIBlockTableLocation = FolioContentTableLocation;
+type FolioAIBlock = FolioContentBlock<FolioAIBlockKind> & {
+  structuralBoundaries?: readonly FolioAIBlockStructuralBoundary[];
 };
+/**
+ * The complete modeled attribute set of one direct `w:pPr/w:spacing` child.
+ * Optional fields preserve the distinction between an absent attribute and
+ * an explicit zero or false value.
+ */
+type FolioAIParagraphSpacing = FolioContentParagraphSpacing;
 /**
  * The paragraph properties an operation may set. A subset of `w:pPrChange`'s
  * scope: properties a comparison can see in a block projection and an agent
@@ -79,6 +55,8 @@ type FolioAIBlockParagraphProperties = {
   listLevel?: number | null;
   /** Direct `w:jc`. `null` clears the override and restores style inheritance. */
   alignment?: document_d_exports.ParagraphAlignment | null;
+  /** Direct `w:spacing` attributes. `null` removes the whole direct child. */
+  spacing?: FolioAIParagraphSpacing | null;
 };
 /**
  * Every paragraph of one story, blank ones included.
@@ -89,8 +67,7 @@ type FolioAIBlockParagraphProperties = {
  * document for a person or a model wants only the paragraphs that carry text,
  * and says so with `isFolioAIContentBlock`.
  */
-type FolioAIEditSnapshot = {
-  blocks: FolioAIBlock[];
+type FolioAIEditSnapshot = FolioContentSnapshot<FolioAIBlock> & {
   anchors: Record<string, FolioAIBlockAnchor>;
 };
 type FolioAIBlockAnchor = {
@@ -100,6 +77,8 @@ type FolioAIBlockAnchor = {
   text: string;
   normalizedText: string;
   textHash: string;
+  /** Hash of zero-width structural boundaries in the clean block view. */
+  structuralBoundaryHash: string;
   hashOccurrenceCount: number;
 };
 type FolioAIComment = {
@@ -218,7 +197,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   id: string;
   type: "formatRange";
   range: FolioAITextRangeHandle;
-  formatting: FolioAIInlineFormatting;
+  formatting: FolioAIInlineFormattingPatch;
 } | {
   id: string;
   type: "insertAfterBlock" | "insertBeforeBlock";
@@ -272,6 +251,11 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * from the anchor and lets the inserted paragraph's style decide.
    */
   alignment?: document_d_exports.ParagraphAlignment | null;
+  /**
+   * Direct `w:spacing` for the inserted block. `null` clears spacing
+   * copied from the anchor and lets the inserted paragraph's style decide.
+   */
+  spacing?: FolioAIParagraphSpacing | null;
   comment?: FolioAIComment;
 } | {
   id: string;
@@ -328,6 +312,16 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    */
   separator?: string;
   blockId: string;
+  /**
+   * Paragraph properties for the first result. Omitted properties keep
+   * the source paragraph's value.
+   */
+  firstParagraphProperties?: FolioAIBlockParagraphProperties;
+  /**
+   * Paragraph properties for the second result. Omitted properties keep
+   * the source paragraph's value.
+   */
+  secondParagraphProperties?: FolioAIBlockParagraphProperties;
 } |
 /**
  * Add a whole table next to the anchor block, its rows marked inserted in
@@ -393,6 +387,11 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    */
   separator?: string;
   blockId: string;
+  /**
+   * Paragraph properties for the joined result. Omitted properties keep
+   * the first paragraph's value.
+   */
+  mergedParagraphProperties?: FolioAIBlockParagraphProperties;
 } | {
   id: string;
   type: "commentOnBlock";
@@ -483,6 +482,10 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
  */
 type FolioAIEditApplyMode = "direct" | "tracked-changes" | "suggested";
 type FolioAIEditSkipReason = "missingBlock" | "changedBlock" | "ambiguousFind" | "missingFind" | "unsupportedBlock" | "unsupportedMode" | "atomicBatchRejected" | "preconditionFailed" | "staleRange" | "emptyOperation" |
+/** The paragraph already owns the one `w:pPrChange` OOXML permits. */
+"pendingParagraphPropertyChange" |
+/** The affected run already owns the one `w:rPrChange` OOXML permits. */
+"pendingRunPropertyChange" |
 /**
  * The operation would not change the document — find equals
  * replace, or replaceBlock's `text` matches the live block.
@@ -571,4 +574,4 @@ type FolioAIEditApplyResult = {
   normalizations?: FolioAIEditNormalization[];
 };
 //#endregion
-export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

package/dist/ai-suggestions/conflict.js

@@ -53,10 +53,7 @@ function resolveSuggestionAnchor(doc, suggestion) {
 				to: point
 			};
 		}
-		return {
-			from: positional.pmPositionAt(originalTextStart),
-			to: positional.pmPositionAt(originalTextEnd - 1) + 1
-		};
+		return positional.pmRangeAt(originalTextStart, originalTextEnd);
 	}
 	return null;
 }

package/dist/ai-suggestions/text-positions.d.ts

@@ -10,6 +10,14 @@ type PositionalText = {
    * preceding block.
    */
   pmPositionAt: (textIndex: number) => number;
+  /**
+   * Resolve a text span without absorbing an explicit zero-width structure.
+   * Returns `null` when the span crosses one.
+   */
+  pmRangeAt: (startTextIndex: number, endTextIndex: number) => {
+    from: number;
+    to: number;
+  } | null;
 };
 /**
  * Walk a slice of the document, returning its text plus a position

package/dist/ai-suggestions/text-positions.js

@@ -8,9 +8,18 @@ const BLOCK_SEPARATOR = "\n";
 function buildPositionalText(doc, from = 0, to = doc.content.size) {
 	const chunks = [];
 	const offsets = [];
+	const structuralBoundaries = [];
 	let textLength = 0;
 	let lastBlockEnd = null;
 	doc.nodesBetween(from, to, (node, pos) => {
+		if (node.type.name === "pageBreakRun") {
+			structuralBoundaries.push({
+				textOffset: textLength,
+				from: pos,
+				to: pos + node.nodeSize
+			});
+			return false;
+		}
 		if (node.isText) {
 			const text = node.text ?? "";
 			const startInNode = Math.max(from, pos);
@@ -35,12 +44,25 @@ function buildPositionalText(doc, from = 0, to = doc.content.size) {
 		}
 		return true;
 	});
+	const text = chunks.join("");
+	const pmPositionAt = (textIndex) => {
+		if (textIndex < 0) return offsets[0] ?? from;
+		if (textIndex >= offsets.length) return (offsets.at(-1) ?? from) + 1;
+		return offsets[textIndex] ?? from;
+	};
 	return {
-		text: chunks.join(""),
-		pmPositionAt: (textIndex) => {
-			if (textIndex < 0) return offsets[0] ?? from;
-			if (textIndex >= offsets.length) return (offsets.at(-1) ?? from) + 1;
-			return offsets[textIndex] ?? from;
+		text,
+		pmPositionAt,
+		pmRangeAt: (startTextIndex, endTextIndex) => {
+			if (!Number.isInteger(startTextIndex) || !Number.isInteger(endTextIndex) || startTextIndex < 0 || endTextIndex <= startTextIndex || endTextIndex > text.length || structuralBoundaries.some(({ textOffset }) => textOffset > startTextIndex && textOffset < endTextIndex)) return null;
+			const rangeFrom = pmPositionAt(startTextIndex);
+			const finalCharacter = offsets[endTextIndex - 1];
+			if (finalCharacter === void 0) return null;
+			const rangeTo = finalCharacter + 1;
+			return rangeFrom <= rangeTo ? {
+				from: rangeFrom,
+				to: rangeTo
+			} : null;
 		}
 	};
 }

package/dist/compare/__fixtures__/body-sequence.js

@@ -88,10 +88,9 @@ const EMPTY_PARAGRAPH = {
 	text: ""
 };
 /**
-* A container may not end with a table: the format requires a paragraph after
-* one, and a body's section properties do not supply it. One rule for both
-* containers, because a fixture that is well formed in a cell and malformed in
-* the body would be measuring two different things.
+* Most fixtures add a paragraph after a table so later paragraph insertions
+* have an explicit anchor. Tests for a schema-valid terminal table remove that
+* convenience paragraph deliberately.
 */
 const closedSequence = (items) => {
 	const last = items.at(-1);

package/dist/compare/column-alignment.d.ts

@@ -1,27 +1,27 @@
-import { FolioAIBlock, FolioAIBlockTableLocation } from "../ai-edits/types.js";
+import { FolioContentBlock, FolioContentTableLocation } from "./content-types.js";
 //#region src/compare/column-alignment.d.ts
-type TableColumnAlignmentStep = {
+type TableColumnAlignmentStep<Block extends FolioContentBlock = FolioContentBlock> = {
   type: "baseColumn";
-  blocks: readonly FolioAIBlock[];
-  location: FolioAIBlockTableLocation;
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
   columnIndex: number;
 } | {
-  type: "targetColumn";
-  blocks: readonly FolioAIBlock[];
-  location: FolioAIBlockTableLocation;
+  type: "revisedColumn";
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
   columnIndex: number;
   anchor: {
     blockId: string;
     position: "after" | "before";
   };
 };
-type TableColumnAlignment = {
-  steps: TableColumnAlignmentStep[];
-  baseBlocks: FolioAIBlock[];
-  targetBlocks: FolioAIBlock[];
+type TableColumnAlignment<Block extends FolioContentBlock = FolioContentBlock> = {
+  steps: TableColumnAlignmentStep<Block>[];
+  baseBlocks: Block[];
+  revisedBlocks: Block[];
   baseColumnKeys: ReadonlyMap<number, number>;
-  targetColumnKeys: ReadonlyMap<number, number>;
+  revisedColumnKeys: ReadonlyMap<number, number>;
 };
-declare const alignTableColumns: (baseBlocks: readonly FolioAIBlock[], targetBlocks: readonly FolioAIBlock[]) => TableColumnAlignment | null;
+declare const alignTableColumns: <Block extends FolioContentBlock>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[]) => TableColumnAlignment<Block> | null;
 //#endregion
 export { TableColumnAlignment, TableColumnAlignmentStep, alignTableColumns };

package/dist/compare/column-alignment.js

@@ -2,7 +2,7 @@ import { panic } from "better-result";
 //#region src/compare/column-alignment.ts
 const MAX_TABLE_GRID_COLUMNS = 63;
 const MAX_TABLE_GRID_AREA = 1e6;
-const tableGridColumns = (blocks) => {
+const extractTableGrid = (blocks) => {
 	const cellsByPhysicalLocation = /* @__PURE__ */ new Map();
 	let width = 0;
 	let height = 0;
@@ -17,7 +17,7 @@ const tableGridColumns = (blocks) => {
 		}
 		const right = location.gridColumnIndex + location.columnSpan;
 		const bottom = location.rowIndex + location.rowSpan;
-		if (location.gridColumnIndex < 0 || location.rowIndex < 0 || location.columnSpan < 1 || location.rowSpan < 1 || right > MAX_TABLE_GRID_COLUMNS) return null;
+		if (!Number.isSafeInteger(location.gridColumnIndex) || !Number.isSafeInteger(location.rowIndex) || !Number.isSafeInteger(location.columnSpan) || !Number.isSafeInteger(location.rowSpan) || !Number.isSafeInteger(right) || !Number.isSafeInteger(bottom) || location.gridColumnIndex < 0 || location.rowIndex < 0 || location.columnSpan < 1 || location.rowSpan < 1 || right > MAX_TABLE_GRID_COLUMNS) return null;
 		cellsByPhysicalLocation.set(key, {
 			blocks: [block],
 			rowIndex: location.rowIndex,
@@ -29,30 +29,58 @@ const tableGridColumns = (blocks) => {
 		height = Math.max(height, bottom);
 	}
 	if (width === 0 || height === 0 || width * height > MAX_TABLE_GRID_AREA) return null;
-	const grid = Array.from({ length: height }, () => Array.from({ length: width }));
-	const ownedCellsByColumn = Array.from({ length: width }, () => []);
-	for (const cell of cellsByPhysicalLocation.values()) {
-		ownedCellsByColumn[cell.gridColumnIndex]?.push(cell);
-		for (let row = cell.rowIndex; row < cell.rowIndex + cell.rowSpan; row++) for (let column = cell.gridColumnIndex; column < cell.gridColumnIndex + cell.columnSpan; column++) {
-			const gridRow = grid[row];
-			if (!gridRow || gridRow[column] !== void 0) return null;
-			gridRow[column] = cell;
+	const occupancyEvents = [...cellsByPhysicalLocation.values()].flatMap((cell) => {
+		const mask = (1n << BigInt(cell.columnSpan)) - 1n << BigInt(cell.gridColumnIndex);
+		return [{
+			rowIndex: cell.rowIndex,
+			type: "enter",
+			mask
+		}, {
+			rowIndex: cell.rowIndex + cell.rowSpan,
+			type: "leave",
+			mask
+		}];
+	});
+	occupancyEvents.sort((left, right) => {
+		const rowOrder = left.rowIndex - right.rowIndex;
+		if (rowOrder !== 0 || left.type === right.type) return rowOrder;
+		return left.type === "leave" ? -1 : 1;
+	});
+	let occupiedColumns = 0n;
+	for (const event of occupancyEvents) {
+		if (event.type === "leave") {
+			occupiedColumns &= ~event.mask;
+			continue;
 		}
+		if ((occupiedColumns & event.mask) !== 0n) return null;
+		occupiedColumns |= event.mask;
 	}
-	return Array.from({ length: width }, (_unused, columnIndex) => {
-		const structuralRows = grid.map((row) => {
-			const cell = row[columnIndex];
-			return cell ? [
-				columnIndex - cell.gridColumnIndex,
-				cell.columnSpan,
-				cell.rowIndex,
-				cell.rowSpan,
-				cell.blocks.map(({ text }) => text)
-			] : null;
-		});
+	return {
+		cells: [...cellsByPhysicalLocation.values()],
+		width,
+		height
+	};
+};
+const tableGridColumns = (grid, internText) => {
+	const coveringCellsByColumn = Array.from({ length: grid.width }, () => []);
+	const ownedCellsByColumn = Array.from({ length: grid.width }, () => []);
+	const textKeysByCell = /* @__PURE__ */ new Map();
+	for (const cell of grid.cells) {
+		textKeysByCell.set(cell, cell.blocks.map(({ text }) => internText(text)));
+		ownedCellsByColumn[cell.gridColumnIndex]?.push(cell);
+		for (let column = cell.gridColumnIndex; column < cell.gridColumnIndex + cell.columnSpan; column++) coveringCellsByColumn[column]?.push(cell);
+	}
+	return Array.from({ length: grid.width }, (_unused, columnIndex) => {
+		const structuralCells = [...coveringCellsByColumn[columnIndex] ?? []].toSorted((left, right) => left.rowIndex - right.rowIndex).map((cell) => [
+			columnIndex - cell.gridColumnIndex,
+			cell.columnSpan,
+			cell.rowIndex,
+			cell.rowSpan,
+			textKeysByCell.get(cell) ?? panic("A table cell has no interned text signature")
+		]);
 		return {
 			index: columnIndex,
-			signature: JSON.stringify(structuralRows),
+			signature: JSON.stringify([grid.height, structuralCells]),
 			ownedCells: ownedCellsByColumn[columnIndex] ?? []
 		};
 	});
@@ -90,14 +118,25 @@ const columnOwnedBlocks = ({ ownedCells }) => {
 	if (ownedCells.length === 0 || ownedCells.some(({ columnSpan }) => columnSpan !== 1)) return null;
 	return ownedCells.flatMap(({ blocks }) => blocks);
 };
-const alignTableColumns = (baseBlocks, targetBlocks) => {
-	const baseColumns = tableGridColumns(baseBlocks);
-	const targetColumns = tableGridColumns(targetBlocks);
-	if (!baseColumns || !targetColumns || baseColumns.length === targetColumns.length) return null;
-	const targetIsWider = targetColumns.length > baseColumns.length;
-	const mapping = uniqueColumnEmbedding(targetIsWider ? baseColumns : targetColumns, targetIsWider ? targetColumns : baseColumns);
+const alignTableColumns = (baseBlocks, revisedBlocks) => {
+	const baseGrid = extractTableGrid(baseBlocks);
+	const revisedGrid = extractTableGrid(revisedBlocks);
+	if (!baseGrid || !revisedGrid || baseGrid.width === revisedGrid.width) return null;
+	const textKeys = /* @__PURE__ */ new Map();
+	let nextTextKey = 0;
+	const internText = (text) => {
+		const existing = textKeys.get(text);
+		if (existing !== void 0) return existing;
+		const key = nextTextKey++;
+		textKeys.set(text, key);
+		return key;
+	};
+	const baseColumns = tableGridColumns(baseGrid, internText);
+	const revisedColumns = tableGridColumns(revisedGrid, internText);
+	const revisedIsWider = revisedColumns.length > baseColumns.length;
+	const mapping = uniqueColumnEmbedding(revisedIsWider ? baseColumns : revisedColumns, revisedIsWider ? revisedColumns : baseColumns);
 	if (!mapping) return null;
-	const widerColumns = targetIsWider ? targetColumns : baseColumns;
+	const widerColumns = revisedIsWider ? revisedColumns : baseColumns;
 	const mapped = new Set(mapping);
 	const unmatchedColumns = widerColumns.filter((_column, index) => !mapped.has(index));
 	const ownedColumns = [];
@@ -109,21 +148,21 @@ const alignTableColumns = (baseBlocks, targetBlocks) => {
 			blocks
 		});
 	}
-	if (ownedColumns.length === 0 || targetIsWider && unmatchedColumns.some(({ ownedCells }) => ownedCells.some(({ rowSpan }) => rowSpan !== 1))) return null;
+	if (ownedColumns.length === 0 || revisedIsWider && unmatchedColumns.some(({ ownedCells }) => ownedCells.some(({ rowSpan }) => rowSpan !== 1))) return null;
 	const unmatchedIds = new Set(ownedColumns.flatMap(({ blocks }) => blocks.map(({ id }) => id)));
 	const baseColumnKeys = /* @__PURE__ */ new Map();
-	const targetColumnKeys = /* @__PURE__ */ new Map();
+	const revisedColumnKeys = /* @__PURE__ */ new Map();
 	mapping.forEach((wideIndex, shortIndex) => {
-		if (targetIsWider) {
+		if (revisedIsWider) {
 			baseColumnKeys.set(shortIndex, shortIndex);
-			targetColumnKeys.set(wideIndex, shortIndex);
+			revisedColumnKeys.set(wideIndex, shortIndex);
 		} else {
 			baseColumnKeys.set(wideIndex, shortIndex);
-			targetColumnKeys.set(shortIndex, shortIndex);
+			revisedColumnKeys.set(shortIndex, shortIndex);
 		}
 	});
 	const steps = [];
-	if (!targetIsWider) for (const { column, blocks } of ownedColumns) {
+	if (!revisedIsWider) for (const { column, blocks } of ownedColumns) {
 		const location = blocks.at(0)?.table;
 		if (!location) return null;
 		steps.push({
@@ -140,7 +179,7 @@ const alignTableColumns = (baseBlocks, targetBlocks) => {
 		const anchorBlock = (rightBaseIndex >= 0 ? baseColumns[rightBaseIndex] : baseColumns[leftBaseIndex])?.ownedCells.at(0)?.blocks.at(0);
 		if (!location || !anchorBlock) return null;
 		steps.push({
-			type: "targetColumn",
+			type: "revisedColumn",
 			blocks,
 			location,
 			columnIndex: column.index,
@@ -152,10 +191,10 @@ const alignTableColumns = (baseBlocks, targetBlocks) => {
 	}
 	return {
 		steps,
-		baseBlocks: baseBlocks.filter(({ id }) => targetIsWider || !unmatchedIds.has(id)),
-		targetBlocks: targetBlocks.filter(({ id }) => !targetIsWider || !unmatchedIds.has(id)),
+		baseBlocks: baseBlocks.filter(({ id }) => revisedIsWider || !unmatchedIds.has(id)),
+		revisedBlocks: revisedBlocks.filter(({ id }) => !revisedIsWider || !unmatchedIds.has(id)),
 		baseColumnKeys,
-		targetColumnKeys
+		revisedColumnKeys
 	};
 };
 //#endregion

package/dist/compare/compare.d.ts

@@ -1,4 +1,4 @@
-import { FolioAIEditSnapshot } from "../ai-edits/types.js";
+import { FolioAIEditSkipReason, FolioAIEditSnapshot } from "../ai-edits/types.js";
 import { WordDiffGranularity } from "../ai-edits/word-diff.js";
 import { FolioRevisionStamp } from "../ai-edits/apply.js";
 import { FolioDocumentStoryHandle, FolioDocxReviewer } from "../ai-edits/headless.js";
@@ -50,7 +50,8 @@ type PlannedStoryComparison = {
  * Stage 2: align every paired story and derive its operations. Pure — no
  * parsing, no serialization, no clock.
  */
-declare const planComparison: ({ pairs }: ParsedComparison) => Result<readonly PlannedStoryComparison[], CompareDocxOperationLimitError>;
+declare const planComparison: ({ pairs, targetReviewer }: ParsedComparison) => Result<readonly PlannedStoryComparison[], CompareDocxOperationLimitError>;
+declare const getCompareSkipDisposition: (reason: FolioAIEditSkipReason) => "fatal" | "unwritable";
 /** What stage 3 produced: the change list, whether it was proven, and whether it wrote anything. */
 type AppliedComparison = {
   changes: readonly CompareChange[];
@@ -111,4 +112,4 @@ declare const serializeComparison: ({ baseBuffer, baseCarriedRevisions, reviewer
  */
 declare const compareDocx: (base: ArrayBuffer, target: ArrayBuffer, options: CompareDocxOptions) => Promise<Result<CompareResult, CompareDocxError>>;
 //#endregion
-export { AppliedComparison, ComparedStoryPair, MAX_COMPARE_OPERATIONS, ParsedComparison, PlannedStoryComparison, applyComparison, compareDocx, parseComparison, planComparison, serializeComparison };
+export { AppliedComparison, ComparedStoryPair, MAX_COMPARE_OPERATIONS, ParsedComparison, PlannedStoryComparison, applyComparison, compareDocx, getCompareSkipDisposition, parseComparison, planComparison, serializeComparison };

package/dist/compare/compare.js

@@ -1,9 +1,11 @@
 import { FolioDocxReviewer } from "../ai-edits/headless.js";
 import { numberingReferenceKeysOf } from "../ai-edits/snapshot.js";
 import { projectTableGeometry } from "../ai-edits/table-geometry.js";
+import { tableTemplateCanCrossPackageLosslessly } from "../ai-edits/table-template.js";
 import { createScopedWordDiffOptions } from "../ai-edits/word-diff.js";
 import "../document-operations.js";
 import { pairFolioDocumentStories } from "../document-stories.js";
+import { createContentComparisonWorkSession } from "./content.js";
 import { planStoryCompare } from "./plan.js";
 import { withFixedPackageDates } from "./reproducible-package.js";
 import { CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "./types.js";
@@ -215,19 +217,49 @@ const parseComparison = async (base, target, options) => {
 		unsupported
 	});
 };
+const planCopiesNonPortableWholeTable = (targetReviewer, pair, plan) => {
+	const targetTables = new Map(targetReviewer.storyTables({ story: pair.targetStory }).map(({ index, node }) => [index, node]));
+	return plan.tableTemplates.some(({ targetRowIndex, targetTableIndex }) => {
+		if (targetRowIndex !== void 0) return false;
+		const table = targetTables.get(targetTableIndex);
+		return table === void 0 || !tableTemplateCanCrossPackageLosslessly(table);
+	});
+};
 /**
 * Stage 2: align every paired story and derive its operations. Pure — no
 * parsing, no serialization, no clock.
 */
-const planComparison = ({ pairs }) => {
+const planComparison = ({ pairs, targetReviewer }) => {
 	const planned = [];
+	const workSession = createContentComparisonWorkSession();
+	let remainingOperations = MAX_COMPARE_OPERATIONS;
 	for (const pair of pairs) {
-		const plan = planStoryCompare({
+		const remainingLcsCells = workSession.alignment.remainingLcsCells;
+		const remainingStructuralTokenLookups = workSession.alignment.remainingStructuralTokenLookups;
+		const remainingMoveComparisons = workSession.remainingMoveComparisons;
+		const remainingMoveTokenLookups = workSession.remainingMoveTokenLookups;
+		let plan = planStoryCompare({
 			story: pair.baseStory,
 			baseSnapshot: pair.baseSnapshot,
 			targetSnapshot: pair.targetSnapshot,
-			maxOperations: MAX_COMPARE_OPERATIONS
+			maxOperations: remainingOperations,
+			wholeTableReplacement: "allow",
+			workSession
 		});
+		if (plan && planCopiesNonPortableWholeTable(targetReviewer, pair, plan)) {
+			workSession.alignment.remainingLcsCells = remainingLcsCells;
+			workSession.alignment.remainingStructuralTokenLookups = remainingStructuralTokenLookups;
+			workSession.remainingMoveComparisons = remainingMoveComparisons;
+			workSession.remainingMoveTokenLookups = remainingMoveTokenLookups;
+			plan = planStoryCompare({
+				story: pair.baseStory,
+				baseSnapshot: pair.baseSnapshot,
+				targetSnapshot: pair.targetSnapshot,
+				maxOperations: remainingOperations,
+				wholeTableReplacement: "avoid",
+				workSession
+			});
+		}
 		if (plan === null) return Result.err(new CompareDocxOperationLimitError({
 			message: "The comparison needs more operations than the engine generates.",
 			limit: MAX_COMPARE_OPERATIONS
@@ -236,6 +268,7 @@ const planComparison = ({ pairs }) => {
 			pair,
 			plan
 		});
+		remainingOperations -= plan.operations.length;
 	}
 	return Result.ok(planned);
 };
@@ -266,10 +299,13 @@ const COMPARE_SKIP_DISPOSITION = {
 	preconditionFailed: "fatal",
 	staleRange: "fatal",
 	emptyOperation: "unwritable",
+	pendingParagraphPropertyChange: "unwritable",
+	pendingRunPropertyChange: "unwritable",
 	noopOperation: "unwritable",
 	documentVersionMismatch: "fatal",
 	documentNotEditable: "fatal"
 };
+const getCompareSkipDisposition = (reason) => COMPARE_SKIP_DISPOSITION[reason];
 /**
 * The table each `insertTable` / `insertTableRow` in the plan should place,
 * resolved against the target document the plan named it in.
@@ -354,7 +390,7 @@ const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity,
 			if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
 			idSeed = nextRevisionId;
 			documentChanged = true;
-			const refused = skipped.filter(({ reason }) => COMPARE_SKIP_DISPOSITION[reason] === "fatal");
+			const refused = skipped.filter(({ reason }) => getCompareSkipDisposition(reason) === "fatal");
 			if (refused.length > 0) return Result.err(new CompareDocxApplyError({
 				message: "Some derived operations were refused, so the result would not match the target.",
 				skipped: refused
@@ -510,4 +546,4 @@ const compareDocx = async (base, target, options) => {
 	});
 };
 //#endregion
-export { MAX_COMPARE_OPERATIONS, applyComparison, compareDocx, parseComparison, planComparison, serializeComparison };
+export { MAX_COMPARE_OPERATIONS, applyComparison, compareDocx, getCompareSkipDisposition, parseComparison, planComparison, serializeComparison };