@stll/folio-core 0.35.1 → 0.37.0

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,8 +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";
@@ -76,16 +79,6 @@ const existingRevisionsOf = (reviewer) => {
 		present
 	};
 };
-/**
-* One story's text-and-structure projection: every block's text tagged with
-* the table cell it sits in. The tag is what makes the self-check below see a
-* paragraph that landed beside a table instead of inside it.
-*/
-const projectBlocks = (blocks) => {
-	return blocks.map(({ text, table, styleId, listLevel }) => {
-		return `${table ? `t${String(table.tableIndex)}r${String(table.rowIndex)}c${String(table.cellIndex)}g${String(table.gridColumnIndex)}x${String(table.columnSpan)}y${String(table.rowSpan)}p${String(table.paragraphIndex)}` : "body"}|${styleId ?? ""}|${listLevel ?? ""}|${text}`;
-	});
-};
 /** Verify formatting only where the plan claims a text-equal formatting change. */
 const formattingRoundTripFailure = ({ invariant, story, changes, actualBlocks, expectedBlocks, expectedBlockId }) => {
 	const expectedIndexById = new Map(expectedBlocks.map(({ id }, index) => [id, index]));
@@ -224,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
@@ -245,6 +268,7 @@ const planComparison = ({ pairs }) => {
 			pair,
 			plan
 		});
+		remainingOperations -= plan.operations.length;
 	}
 	return Result.ok(planned);
 };
@@ -275,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.
@@ -321,14 +348,14 @@ const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity,
 	const failures = [];
 	let idSeed = revisionStamp.idSeed;
 	let documentChanged = false;
+	const wordDiff = createScopedWordDiffOptions({ granularity });
 	for (const { pair, plan } of planned) {
 		changes.push(...plan.changes);
 		if (plan.operations.length === 0 && plan.tableGeometryPairings.length === 0) continue;
-		const baseBeforeBlocks = reviewer.readReviewedStory({
+		const baseBefore = reviewer.readReviewedStory({
 			story: pair.baseStory,
 			view: "final"
 		})?.snapshot.blocks ?? [];
-		const baseBefore = projectBlocks(baseBeforeBlocks);
 		const baseBeforeGeometry = projectTableGeometry(reviewer.storyTables({ story: pair.baseStory }));
 		const targetTables = new Map(targetReviewer.storyTables({ story: pair.targetStory }).map(({ index, node }) => [index, node]));
 		const afterGeometry = reviewer.matchStoryTableGeometry({
@@ -352,7 +379,7 @@ const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity,
 					date: revisionStamp.date,
 					idSeed
 				},
-				wordDiff: { granularity },
+				wordDiff,
 				batch: {
 					version: 1,
 					mode: "tracked-changes",
@@ -363,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
@@ -376,8 +403,8 @@ const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity,
 		const acceptFailure = classifyProjectionMismatch({
 			invariant: "accept-reproduces-target",
 			story: pair.baseStory,
-			actual: projectBlocks(acceptedStory?.snapshot.blocks ?? []),
-			expected: projectBlocks(pair.targetSnapshot.blocks)
+			actual: acceptedStory?.snapshot.blocks ?? [],
+			expected: pair.targetSnapshot.blocks
 		});
 		if (acceptFailure) failures.push(acceptFailure);
 		else {
@@ -398,7 +425,7 @@ const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity,
 		const rejectFailure = classifyProjectionMismatch({
 			invariant: "reject-reproduces-base",
 			story: pair.baseStory,
-			actual: projectBlocks(rejectedStory?.snapshot.blocks ?? []),
+			actual: rejectedStory?.snapshot.blocks ?? [],
 			expected: baseBefore
 		});
 		if (rejectFailure) failures.push(rejectFailure);
@@ -519,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 };

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

@@ -0,0 +1,95 @@
+import { FolioContentBlock, FolioContentIdStability, FolioContentTableLocation } from "./content-types.js";
+import { TableColumnAlignmentStep } from "./column-alignment.js";
+//#region src/compare/content-alignment.d.ts
+type FolioContentAlignmentWorkSession = {
+  remainingLcsCells: number;
+  remainingStructuralTokenLookups: number;
+};
+type CreateFolioContentAlignmentWorkSessionOptions = {
+  /** @internal A lower allowance used by focused boundary tests. */
+  lcsCells?: number;
+  /** @internal A lower allowance used by focused boundary tests. */
+  structuralTokenLookups?: number;
+};
+declare const createFolioContentAlignmentWorkSession: (options?: CreateFolioContentAlignmentWorkSessionOptions) => FolioContentAlignmentWorkSession;
+declare const exceedsFolioContentLcsBudget: (baseCount: number, revisedCount: number) => boolean;
+type FolioContentBlockPair = {
+  baseIndex: number;
+  revisedIndex: number;
+};
+/**
+ * Longest strictly increasing subsequence by revised index.
+ *
+ * The Fenwick tree stores the earliest end index for equal-length candidates,
+ * preserving the historical deterministic tie break while reducing the
+ * stable-anchor pass from quadratic to O(n log n).
+ */
+declare const longestIncreasingFolioContentPairs: (pairs: readonly FolioContentBlockPair[]) => FolioContentBlockPair[];
+type FolioContentAlignedBlockEvent<Block extends FolioContentBlock = FolioContentBlock> = {
+  type: "pair";
+  baseBlock: Block;
+  revisedBlock: Block;
+} | {
+  type: "baseOnly";
+  block: Block;
+} | {
+  type: "revisedOnly";
+  block: Block;
+};
+type AlignFolioContentBlocksOptions<Block extends FolioContentBlock> = {
+  workSession?: FolioContentAlignmentWorkSession;
+  /** Let an already-aligned structural slot outrank differing authored IDs. */
+  stableIdMismatch?: "pair" | "separate";
+  /** @internal Compatibility hook for adapters whose source model predates `idStability`. */
+  idStability?: ((block: Block) => FolioContentIdStability) | undefined;
+};
+declare const alignFolioContentBlocks: <Block extends FolioContentBlock>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[], options?: AlignFolioContentBlocksOptions<Block>) => FolioContentAlignedBlockEvent<Block>[];
+type FolioContentAlignmentStep<Block extends FolioContentBlock = FolioContentBlock> = {
+  type: "pair";
+  baseBlock: Block;
+  revisedBlock: Block;
+} | {
+  type: "baseOnly";
+  block: Block;
+  moveScope: FolioContentMoveScope;
+} | {
+  type: "revisedOnly";
+  block: Block;
+  moveScope: FolioContentMoveScope;
+} | {
+  type: "baseRow";
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
+} | {
+  type: "revisedRow";
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
+} | {
+  type: "baseTable";
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
+} | {
+  type: "revisedTable";
+  blocks: readonly Block[];
+  location: FolioContentTableLocation;
+} | TableColumnAlignmentStep<Block>;
+/** @internal Legal move bucket and alignment gap for one unpaired block. */
+type FolioContentMoveScope = {
+  readonly bucket: number;
+  readonly gap: number;
+};
+declare const groupFolioContentTableRows: <Block extends FolioContentBlock>(blocks: readonly Block[]) => Block[][];
+type AlignFolioContentStructureOptions<Block extends FolioContentBlock> = {
+  baseBlocks: readonly Block[];
+  revisedBlocks: readonly Block[];
+  workSession?: FolioContentAlignmentWorkSession;
+  wholeTableReplacement?: "allow" | "avoid";
+  /** Let a structurally aligned slot outrank different stable identifiers. */
+  stableIdMismatch?: "pair" | "separate";
+  /** @internal Compatibility hook for adapters whose source model predates `idStability`. */
+  idStability?: ((block: Block) => FolioContentIdStability) | undefined;
+};
+declare const alignFolioContentStructure: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, workSession, wholeTableReplacement, stableIdMismatch, idStability }: AlignFolioContentStructureOptions<Block>) => FolioContentAlignmentStep<Block>[];
+declare const contentBlocksShareContainer: (left: FolioContentBlock, right: FolioContentBlock) => boolean;
+//#endregion
+export { AlignFolioContentBlocksOptions, AlignFolioContentStructureOptions, CreateFolioContentAlignmentWorkSessionOptions, FolioContentAlignedBlockEvent, FolioContentAlignmentStep, FolioContentAlignmentWorkSession, FolioContentBlockPair, FolioContentMoveScope, alignFolioContentBlocks, alignFolioContentStructure, contentBlocksShareContainer, createFolioContentAlignmentWorkSession, exceedsFolioContentLcsBudget, groupFolioContentTableRows, longestIncreasingFolioContentPairs };