@stll/folio-core 0.32.2 → 0.33.0

package/dist/compare/plan.js

@@ -0,0 +1,1059 @@
+import { createFolioAITextRangeHandle, trailingBodyBlockId } from "../ai-edits/snapshot.js";
+import { alignFolioBlocks } from "../version-comparison.js";
+import { alignTableColumns } from "./column-alignment.js";
+import { inlineFormattingSegments } from "./formatting.js";
+import { panic } from "better-result";
+//#region src/compare/plan.ts
+/**
+* Turn two block snapshots of one story into the change list a caller reads
+* and the {@link FolioAIEditOperation}s that reproduce the target when every
+* generated tracked change is accepted.
+*
+* Pure: no parsing, no serialization, no clock. Every alignment runs through
+* {@link alignFolioBlocks}, shared with the version-diff and redline paths.
+*
+* ## Aligning by container, not by block
+*
+* A single alignment over every paragraph in the story cannot see structure.
+* It pairs on text and document order, so it will put a paragraph inside a
+* table cell opposite one outside it, or a cell of one row opposite a cell of
+* the next — and rewriting either pair in place leaves the target's text in
+* the wrong container. A whole row that was added or removed likewise arrives
+* as a scatter of unmatched paragraphs, which no block operation can turn back
+* into a row: a block insertion anchored in a table lands beside the table,
+* never as a new row in it.
+*
+* So the story is aligned in three nested passes, each over things that can
+* actually stand in for one another:
+*
+* 1. **Segments.** Maximal runs of body text and of one table each, so a table
+*    is only ever compared against a table.
+* 2. **Rows**, within a paired table segment, so a whole-row change stays whole
+*    and becomes `insertTableRow` / `deleteTableRow`.
+* 3. **Cells**, within a paired row, matched by physical cell index.
+*
+* ## Move detection
+*
+* A base-only and a target-only block with identical text and at least
+* {@link MOVE_MINIMUM_WORD_COUNT} words are one relocation. The operations stay
+* a delete plus an insert — the tracked-change grammar Word round-trips has no
+* durable "moved from here" mark on this path — but the change list reports a
+* single `move` so the relocation is not read as unrelated churn. The word
+* floor keeps boilerplate one-liners from pairing as spurious moves.
+*/
+/** Words a relocated block needs before the move pass will pair it. */
+const MOVE_MINIMUM_WORD_COUNT = 3;
+/**
+* Cap on same-text base-only blocks the move pass keeps per text. Without it a
+* document repeating one paragraph thousands of times would make the pass
+* quadratic on attacker-controlled input.
+*/
+const MAX_MOVE_CANDIDATES_PER_TEXT = 64;
+/**
+* How much of a relocated paragraph must survive the relocation for it still
+* to read as one. Below it the two paragraphs are a deletion and an unrelated
+* insertion, and calling them a move would tell the reader the wrong story
+* about where the text came from.
+*/
+const MOVE_SIMILARITY_THRESHOLD = .8;
+/**
+* Total pair comparisons the similarity pass may make in one story. Exact text
+* matches are found by lookup; only what is left pays this, and it is capped
+* so two documents of unmatched paragraphs cannot make the pass quadratic.
+*/
+const MAX_MOVE_SIMILARITY_COMPARISONS = 2e4;
+/**
+* Dice coefficient over word tokens: twice the shared tokens over the two
+* token counts. Multiset rather than set, so a paragraph repeating a word does
+* not match one that says it once.
+*/
+const tokenSimilarity = (left, right) => {
+	const leftTokens = left.split(/\s+/u).filter((token) => token.length > 0);
+	const rightTokens = right.split(/\s+/u).filter((token) => token.length > 0);
+	if (leftTokens.length === 0 || rightTokens.length === 0) return 0;
+	const remaining = /* @__PURE__ */ new Map();
+	for (const token of leftTokens) remaining.set(token, (remaining.get(token) ?? 0) + 1);
+	let shared = 0;
+	for (const token of rightTokens) {
+		const count = remaining.get(token) ?? 0;
+		if (count > 0) {
+			remaining.set(token, count - 1);
+			shared += 1;
+		}
+	}
+	return 2 * shared / (leftTokens.length + rightTokens.length);
+};
+const wordCountReaches = (text, minimum) => {
+	let count = 0;
+	for (const word of text.split(/\s+/u)) if (word.length > 0 && ++count >= minimum) return true;
+	return false;
+};
+/**
+* The document's segments, normalized to strictly alternate body, table, body,
+* ... and to begin and end with a body segment — inserting empty body segments
+* where the document has none.
+*
+* Without the padding the two sides can hold different segment shapes (a
+* document that opens with a table against one that opens with a heading), and
+* the alignment's positional fallback would then put a body segment opposite a
+* table. That pair is unusable, so the whole table would be reissued as a
+* deletion plus an insertion. Padding keeps like opposite like.
+*/
+const splitSegments = (blocks) => {
+	const segments = [];
+	let currentTableIndex = null;
+	for (const block of blocks) {
+		const tableIndex = block.table?.outerTableIndex ?? null;
+		const current = segments.at(-1);
+		if (current !== void 0 && currentTableIndex === tableIndex) {
+			current.blocks.push(block);
+			continue;
+		}
+		if (block.table && segments.at(-1)?.kind !== "body") segments.push({
+			kind: "body",
+			blocks: []
+		});
+		segments.push({
+			kind: block.table ? "table" : "body",
+			blocks: [block]
+		});
+		currentTableIndex = tableIndex;
+	}
+	if (segments.length === 0 || segments.at(-1)?.kind === "table") segments.push({
+		kind: "body",
+		blocks: []
+	});
+	return segments;
+};
+/**
+* Blocks of one table segment grouped into rows, in document order.
+*
+* Keyed by table AND row, not by row alone: a segment holds the whole
+* outermost table, so a nested table's first row would otherwise merge with
+* its parent's first row and the alignment would compare one against the
+* other.
+*/
+const groupRows = (blocks) => {
+	const rows = /* @__PURE__ */ new Map();
+	for (const block of blocks) {
+		if (!block.table) continue;
+		const key = `${String(block.table.tableIndex)}:${String(block.table.rowIndex)}`;
+		const row = rows.get(key);
+		if (row) row.push(block);
+		else rows.set(key, [block]);
+	}
+	return [...rows.values()];
+};
+const rowText = (row) => row.map(({ text }) => text).join(" ");
+const rowLocation = (row) => row.at(0)?.table ?? null;
+/** Zip one paired row's cells by physical cell index, then by paragraph order. */
+const alignRowCells = (baseRow, targetRow, baseColumnKeys, targetColumnKeys) => {
+	const byCell = (row, columnKeys) => {
+		const cells = /* @__PURE__ */ new Map();
+		for (const block of row) {
+			const table = block.table;
+			let cellIndex = table?.cellIndex ?? 0;
+			if (table && columnKeys) {
+				const alignedColumn = columnKeys.get(table.gridColumnIndex);
+				if (alignedColumn === void 0) return panic("A paired table cell has no aligned grid column", { gridColumnIndex: table.gridColumnIndex });
+				cellIndex = alignedColumn;
+			}
+			const blocks = cells.get(cellIndex);
+			if (blocks) blocks.push(block);
+			else cells.set(cellIndex, [block]);
+		}
+		return cells;
+	};
+	const baseCells = byCell(baseRow, baseColumnKeys);
+	const targetCells = byCell(targetRow, targetColumnKeys);
+	const cellIndexes = [.../* @__PURE__ */ new Set([...baseCells.keys(), ...targetCells.keys()])].toSorted((left, right) => left - right);
+	const steps = [];
+	for (const cellIndex of cellIndexes) {
+		const baseBlocks = baseCells.get(cellIndex) ?? [];
+		const targetBlocks = targetCells.get(cellIndex) ?? [];
+		const paired = Math.min(baseBlocks.length, targetBlocks.length);
+		for (let index = 0; index < paired; index++) {
+			const baseBlock = baseBlocks[index];
+			const targetBlock = targetBlocks[index];
+			if (baseBlock && targetBlock) steps.push({
+				type: "pair",
+				baseBlock,
+				targetBlock
+			});
+		}
+		for (const block of baseBlocks.slice(paired)) steps.push({
+			type: "baseOnly",
+			block
+		});
+		for (const block of targetBlocks.slice(paired)) steps.push({
+			type: "targetOnly",
+			block
+		});
+	}
+	return steps;
+};
+/**
+* Align one table's rows, then its cells.
+*
+* Running the block alignment straight over a table's paragraphs cannot see
+* rows: it happily pairs a cell of one row with a cell of another, and a row
+* that was wholly added or removed shows up as a scatter of unmatched
+* paragraphs. Aligning rows first — each row standing in as one proxy block of
+* its joined cell text — keeps a whole-row change whole, and confines every
+* other difference to a cell that really corresponds.
+*/
+/**
+* One segment's blocks split per table, in first-appearance order. A segment
+* is a whole outermost table, so it holds the parent's blocks and every nested
+* table's; a row alignment that mixed them would compare the parent's first
+* row against a nested table's.
+*/
+const groupTables = (blocks) => {
+	const tables = /* @__PURE__ */ new Map();
+	for (const block of blocks) {
+		if (!block.table) continue;
+		const existing = tables.get(block.table.tableIndex);
+		if (existing) existing.push(block);
+		else tables.set(block.table.tableIndex, [block]);
+	}
+	return [...tables.values()];
+};
+/**
+* Align a paired table segment: each table in it against the table at the same
+* place on the other side, then that table's rows, then its cells. Tables are
+* paired by order within the segment because the segment IS one table plus
+* whatever nests inside it — the nth nested table of one answers to the nth of
+* the other.
+*/
+const buildTableSegmentSteps = (baseBlocks, targetBlocks) => {
+	const baseTables = groupTables(baseBlocks);
+	const targetTables = groupTables(targetBlocks);
+	const steps = [];
+	const paired = Math.min(baseTables.length, targetTables.length);
+	for (let index = 0; index < paired; index++) steps.push(...buildTableSteps(baseTables[index] ?? [], targetTables[index] ?? []));
+	for (const blocks of baseTables.slice(paired)) {
+		const location = blocks.at(0)?.table;
+		if (location) steps.push({
+			type: "baseTable",
+			blocks,
+			location
+		});
+	}
+	for (const blocks of targetTables.slice(paired)) {
+		const location = blocks.at(0)?.table;
+		if (location) steps.push({
+			type: "targetTable",
+			blocks,
+			location
+		});
+	}
+	return steps;
+};
+/**
+* How alike two rows must be for one to be read as the other, edited. Below
+* it the pair is a deleted row and an inserted one.
+*/
+const ROW_PAIR_SIMILARITY = .5;
+/**
+* How alike two rows are: their text, halved when their shapes differ.
+*
+* A row's shape is its physical cell count. Two rows with the same words in a
+* different number of cells are not the same row edited, and pairing them
+* would report every cell as changed rather than the row as replaced.
+*/
+const rowSimilarity = (base, target) => {
+	if (!base || !target) return 0;
+	const text = tokenSimilarity(rowText(base), rowText(target));
+	return rowCellTexts(base).length === rowCellTexts(target).length ? text : text / 2;
+};
+/**
+* Align one table's rows.
+*
+* Exact text first, then SIMILARITY rather than position. Positional fallback
+* is what made a deleted row plus a few cell edits report as a change in every
+* row of the table: each row was paired with the one below it, so every cell
+* differed. Pairing on similarity, and stepping one row on the side whose next
+* row matches better, keeps the deletion where it happened.
+*/
+const alignTableRows = (baseRows, targetRows, baseColumnKeys, targetColumnKeys) => {
+	const steps = [];
+	const pushRow = (row, side) => {
+		const location = rowLocation(row);
+		if (location) steps.push({
+			type: side === "base" ? "baseRow" : "targetRow",
+			blocks: row,
+			location
+		});
+	};
+	let baseCursor = 0;
+	let targetCursor = 0;
+	while (baseCursor < baseRows.length && targetCursor < targetRows.length) {
+		const baseRow = baseRows[baseCursor];
+		const targetRow = targetRows[targetCursor];
+		if (!baseRow || !targetRow) break;
+		const here = rowSimilarity(baseRow, targetRow);
+		if (here < 1) {
+			const baseAhead = rowSimilarity(baseRows[baseCursor + 1], targetRow);
+			const targetAhead = rowSimilarity(baseRow, targetRows[targetCursor + 1]);
+			if (baseAhead >= ROW_PAIR_SIMILARITY && baseAhead > here && baseAhead >= targetAhead) {
+				pushRow(baseRow, "base");
+				baseCursor += 1;
+				continue;
+			}
+			if (targetAhead >= ROW_PAIR_SIMILARITY && targetAhead > here) {
+				pushRow(targetRow, "target");
+				targetCursor += 1;
+				continue;
+			}
+		}
+		steps.push(...alignRowCells(baseRow, targetRow, baseColumnKeys, targetColumnKeys));
+		baseCursor += 1;
+		targetCursor += 1;
+	}
+	for (const row of baseRows.slice(baseCursor)) pushRow(row, "base");
+	for (const row of targetRows.slice(targetCursor)) pushRow(row, "target");
+	return steps;
+};
+const buildTableSteps = (baseBlocks, targetBlocks) => {
+	const columns = alignTableColumns(baseBlocks, targetBlocks);
+	return columns ? [...columns.steps, ...alignTableRows(groupRows(columns.baseBlocks), groupRows(columns.targetBlocks), columns.baseColumnKeys, columns.targetColumnKeys)] : alignTableRows(groupRows(baseBlocks), groupRows(targetBlocks));
+};
+const buildBodySteps = (baseBlocks, targetBlocks) => alignFolioBlocks(baseBlocks, targetBlocks).map((event) => {
+	switch (event.type) {
+		case "pair": return {
+			type: "pair",
+			baseBlock: event.baseBlock,
+			targetBlock: event.revisedBlock
+		};
+		case "baseOnly": return {
+			type: "baseOnly",
+			block: event.block
+		};
+		case "revisedOnly": return {
+			type: "targetOnly",
+			block: event.block
+		};
+		default: return panic("Unhandled block alignment event", { event });
+	}
+});
+/**
+* Every block of an unpaired segment, as one-sided steps. A whole table stays
+* whole: reissuing it row by row would need a table to put the rows in, and
+* the point of an unpaired table segment is that there is none.
+*/
+const unpairedSegmentSteps = (segment, side) => {
+	if (segment.kind !== "table") return segment.blocks.map((block) => side === "base" ? {
+		type: "baseOnly",
+		block
+	} : {
+		type: "targetOnly",
+		block
+	});
+	const location = segment.blocks.at(0)?.table;
+	if (!location) return [];
+	return [{
+		type: side === "base" ? "baseTable" : "targetTable",
+		blocks: segment.blocks,
+		location
+	}];
+};
+/**
+* Align the two stories segment by segment, in order.
+*
+* Segments are paired by position rather than by text. Both sides have been
+* normalized to the same alternating shape, so position already carries the
+* meaning: the nth table of one document answers to the nth table of the
+* other, and the body text between two tables answers to the body text between
+* the same two tables. Matching segments on text instead lets a paragraph that
+* moved across a table steal the table's own pairing, which reissues the whole
+* table as a deletion and an insertion.
+*
+* When the two documents hold different numbers of tables the shapes diverge,
+* and the surplus segments are reported one-sided. The operation builder turns
+* those segments into `insertTable` or `deleteTable` operations.
+*/
+const segmentText = (segment) => segment.blocks.map(({ text }) => text).join(" ");
+/**
+* How alike two table segments must be before a lookahead match may steal the
+* pairing from the table in front of it. Two tables drawn from one document's
+* vocabulary score alike by chance, so a lookahead has to clear this bar as
+* well as beat what it displaces.
+*/
+const TABLE_PAIR_SIMILARITY = .5;
+/**
+* Pair the two segment sequences, marking the segments only one side has.
+*
+* Pairing by index cannot see a table added or removed: the nth table of one
+* document is put opposite the nth of the other, so deleting the first table
+* shifts every later one and the comparison rewrites each table's contents
+* into the next table along. Segments strictly alternate body, table, body,
+* ..., so a one-segment lookahead on each side is enough to tell "this table
+* changed a lot" from "this table is gone": the next table on the other side
+* matching better is what says the current one is unpaired.
+*/
+const alignSegments = (baseSegments, targetSegments) => {
+	const paired = [];
+	const similarity = (left, right) => left === void 0 || right === void 0 || left.kind !== right.kind ? 0 : tokenSimilarity(segmentText(left), segmentText(right));
+	let baseCursor = 0;
+	let targetCursor = 0;
+	while (baseCursor < baseSegments.length && targetCursor < targetSegments.length) {
+		const baseSegment = baseSegments[baseCursor];
+		const targetSegment = targetSegments[targetCursor];
+		if (!baseSegment || !targetSegment) break;
+		if (baseSegment.kind !== targetSegment.kind) {
+			paired.push({
+				baseSegment,
+				targetSegment: null
+			});
+			baseCursor += 1;
+			continue;
+		}
+		if (baseSegment.kind === "body") {
+			paired.push({
+				baseSegment,
+				targetSegment
+			});
+			baseCursor += 1;
+			targetCursor += 1;
+			continue;
+		}
+		const here = similarity(baseSegment, targetSegment);
+		const baseAhead = similarity(baseSegments[baseCursor + 2], targetSegment);
+		const targetAhead = similarity(baseSegment, targetSegments[targetCursor + 2]);
+		if (baseAhead >= TABLE_PAIR_SIMILARITY && baseAhead > here && baseAhead >= targetAhead) {
+			paired.push({
+				baseSegment,
+				targetSegment: null
+			});
+			baseCursor += 1;
+			continue;
+		}
+		if (targetAhead >= TABLE_PAIR_SIMILARITY && targetAhead > here) {
+			paired.push({
+				baseSegment: null,
+				targetSegment
+			});
+			targetCursor += 1;
+			continue;
+		}
+		paired.push({
+			baseSegment,
+			targetSegment
+		});
+		baseCursor += 1;
+		targetCursor += 1;
+	}
+	for (const segment of baseSegments.slice(baseCursor)) paired.push({
+		baseSegment: segment,
+		targetSegment: null
+	});
+	for (const segment of targetSegments.slice(targetCursor)) paired.push({
+		baseSegment: null,
+		targetSegment: segment
+	});
+	return paired;
+};
+const isEmptyParagraphNode = (block, snapshot) => {
+	const anchor = snapshot.anchors[block.id] ?? panic("A comparison snapshot block has no matching anchor", { blockId: block.id });
+	return block.text === "" && block.table === void 0 && anchor.to - anchor.from === 2;
+};
+const buildSteps = ({ story, baseSnapshot, targetSnapshot }) => {
+	const baseBlocks = baseSnapshot.blocks;
+	const targetBlocks = targetSnapshot.blocks;
+	const baseLast = baseBlocks.at(-1);
+	const targetLast = targetBlocks.at(-1);
+	const terminalCarrierPair = story.type === "main" && baseLast !== void 0 && isEmptyParagraphNode(baseLast, baseSnapshot) && targetLast !== void 0 && isEmptyParagraphNode(targetLast, targetSnapshot) ? {
+		type: "pair",
+		baseBlock: baseLast,
+		targetBlock: targetLast
+	} : null;
+	const alignedBaseBlocks = terminalCarrierPair ? baseBlocks.slice(0, -1) : baseBlocks;
+	const alignedTargetBlocks = terminalCarrierPair ? targetBlocks.slice(0, -1) : targetBlocks;
+	const steps = [];
+	for (const { baseSegment, targetSegment } of alignSegments(splitSegments(alignedBaseBlocks), splitSegments(alignedTargetBlocks))) {
+		if (baseSegment && targetSegment) {
+			steps.push(...baseSegment.kind === "table" ? buildTableSegmentSteps(baseSegment.blocks, targetSegment.blocks) : buildBodySteps(baseSegment.blocks, targetSegment.blocks));
+			continue;
+		}
+		if (baseSegment) {
+			steps.push(...unpairedSegmentSteps(baseSegment, "base"));
+			continue;
+		}
+		if (targetSegment) steps.push(...unpairedSegmentSteps(targetSegment, "target"));
+	}
+	if (terminalCarrierPair) steps.push(terminalCarrierPair);
+	return steps;
+};
+/**
+* Two blocks are in the same container when a paragraph mark between them
+* exists at all: two body paragraphs, or two paragraphs of one table cell. A
+* mark cannot span a cell boundary, so a split or a merge across one is not a
+* paragraph-mark edit however similar the text looks.
+*/
+const shareAContainer = (left, right) => {
+	if (!left.table || !right.table) return left.table === void 0 && right.table === void 0;
+	return left.table.tableIndex === right.table.tableIndex && left.table.rowIndex === right.table.rowIndex && left.table.cellIndex === right.table.cellIndex;
+};
+/**
+* The text between `head` and `tail` inside `whole`, when `whole` is exactly
+* the two joined by whitespace (or by nothing). `null` when it is not: any
+* other difference is a rewrite, not a moved paragraph mark.
+*/
+const separatorBetween = (whole, head, tail) => {
+	if (head.length === 0 || tail.length === 0 || whole.length < head.length + tail.length) return null;
+	if (!whole.startsWith(head) || !whole.endsWith(tail)) return null;
+	const separator = whole.slice(head.length, whole.length - tail.length);
+	return separator.length === 0 || /^\s+$/u.test(separator) ? separator : null;
+};
+/**
+* Where the alignment produced a rewrite plus an insertion or a deletion that
+* is really one paragraph mark moving, by step index of the PAIR step. The
+* step after it is consumed with it.
+*
+* The alignment cannot see this: it pairs the base paragraph with the target
+* half that still matches it and leaves the other half unpaired, which is a
+* correct alignment and a misleading redline.
+*/
+const detectParagraphMarkEdits = (steps) => {
+	const plans = /* @__PURE__ */ new Map();
+	for (const [index, step] of steps.entries()) {
+		const next = steps[index + 1];
+		if (step.type !== "pair" || next === void 0) continue;
+		if (next.type === "targetOnly") {
+			const separator = separatorBetween(step.baseBlock.text, step.targetBlock.text, next.block.text);
+			if (separator !== null && shareAContainer(step.targetBlock, next.block)) plans.set(index, {
+				type: "split",
+				baseBlock: step.baseBlock,
+				targetBlocks: [step.targetBlock, next.block],
+				offset: step.targetBlock.text.length,
+				separator
+			});
+			continue;
+		}
+		if (next.type !== "baseOnly") continue;
+		const separator = separatorBetween(step.targetBlock.text, step.baseBlock.text, next.block.text);
+		if (separator !== null && shareAContainer(step.baseBlock, next.block)) plans.set(index, {
+			type: "merge",
+			baseBlocks: [step.baseBlock, next.block],
+			targetBlock: step.targetBlock,
+			separator
+		});
+	}
+	return plans;
+};
+/** Base block id -> target block id for every relocation the move pass found. */
+const detectMoves = (steps, consumed) => {
+	const candidatesByText = /* @__PURE__ */ new Map();
+	for (const [index, step] of steps.entries()) {
+		if (consumed.has(index) || step.type !== "baseOnly" || !wordCountReaches(step.block.text, MOVE_MINIMUM_WORD_COUNT)) continue;
+		const queue = candidatesByText.get(step.block.text);
+		if (!queue) {
+			candidatesByText.set(step.block.text, [step.block.id]);
+			continue;
+		}
+		if (queue.length < MAX_MOVE_CANDIDATES_PER_TEXT) queue.push(step.block.id);
+	}
+	const unmatched = [];
+	for (const [index, step] of steps.entries()) {
+		if (consumed.has(index) || step.type !== "baseOnly" || !wordCountReaches(step.block.text, MOVE_MINIMUM_WORD_COUNT)) continue;
+		unmatched.push(step.block);
+	}
+	const movesByBaseBlockId = /* @__PURE__ */ new Map();
+	const takenBaseBlockIds = /* @__PURE__ */ new Set();
+	let comparisonBudget = MAX_MOVE_SIMILARITY_COMPARISONS;
+	for (const [index, step] of steps.entries()) {
+		if (consumed.has(index) || step.type !== "targetOnly") continue;
+		const exact = candidatesByText.get(step.block.text)?.shift();
+		if (exact !== void 0) {
+			takenBaseBlockIds.add(exact);
+			movesByBaseBlockId.set(exact, step.block.id);
+			continue;
+		}
+		if (!wordCountReaches(step.block.text, MOVE_MINIMUM_WORD_COUNT)) continue;
+		let best = null;
+		for (const candidate of unmatched) {
+			if (comparisonBudget <= 0) break;
+			if (takenBaseBlockIds.has(candidate.id)) continue;
+			comparisonBudget -= 1;
+			const similarity = tokenSimilarity(candidate.text, step.block.text);
+			if (similarity >= MOVE_SIMILARITY_THRESHOLD && (best === null || similarity > best.similarity)) best = {
+				block: candidate,
+				similarity
+			};
+		}
+		if (best) {
+			takenBaseBlockIds.add(best.block.id);
+			movesByBaseBlockId.set(best.block.id, step.block.id);
+		}
+	}
+	return movesByBaseBlockId;
+};
+/**
+* For each step, the id of the next base block at or after it — the anchor a
+* target-only insertion is placed before. `null` once no base block follows.
+*/
+const nextBaseBlockIdByStep = (steps) => {
+	const anchors = Array.from({ length: steps.length });
+	let next = null;
+	for (let index = steps.length - 1; index >= 0; index--) {
+		anchors[index] = next;
+		const step = steps[index];
+		if (step?.type === "pair") next = step.baseBlock.id;
+		else if (step?.type === "baseOnly") next = step.block.id;
+		else if (step?.type === "baseRow") next = step.blocks[0]?.id ?? next;
+		else if (step?.type === "baseColumn") next = step.blocks[0]?.id ?? next;
+	}
+	return anchors;
+};
+const baseTableBlockOf = (step) => {
+	switch (step.type) {
+		case "pair": return step.baseBlock.table ? step.baseBlock : null;
+		case "baseOnly": return step.block.table ? step.block : null;
+		case "baseRow":
+		case "baseTable":
+		case "baseColumn": return step.blocks[0] ?? null;
+		case "targetOnly":
+		case "targetRow":
+		case "targetTable":
+		case "targetColumn": return null;
+		default: return panic("Unhandled compare step", { step });
+	}
+};
+/**
+* The base-document row a new row is inserted next to: the nearest base block
+* inside a table, preferring the one before the insertion so a run of new rows
+* keeps its order.
+*/
+const findRowAnchor = (steps, stepIndex) => {
+	for (let index = stepIndex - 1; index >= 0; index--) {
+		const step = steps[index];
+		const block = step ? baseTableBlockOf(step) : null;
+		if (block) return {
+			blockId: block.id,
+			position: "after"
+		};
+	}
+	for (let index = stepIndex + 1; index < steps.length; index++) {
+		const step = steps[index];
+		const block = step ? baseTableBlockOf(step) : null;
+		if (block) return {
+			blockId: block.id,
+			position: "before"
+		};
+	}
+	return null;
+};
+/**
+* A row's text per physical cell, indexed BY cell so an empty cell keeps its
+* slot. An empty cell carries no block at all, so packing only the cells that
+* have text would shift every later cell one column left.
+*/
+/** One table's cell texts, row by row, for a whole-table change. */
+/**
+* One table's cell texts, row by row, padded to the widest row.
+*
+* A row's own width is its highest occupied cell index, so a table with
+* merged cells or a short last row produces a ragged grid — and a ragged grid
+* is not a table any consumer can lay out. Padding states the grid the table
+* actually occupies; the empty strings are the cells a `w:gridSpan` covers.
+*/
+const tableCellTexts = (blocks) => {
+	const rows = groupRows(blocks).map((row) => rowCellTexts(row));
+	let width = 0;
+	for (const row of rows) width = Math.max(width, row.length);
+	for (const row of rows) while (row.length < width) row.push("");
+	return rows;
+};
+const rowCellTexts = (blocks) => {
+	const byCell = [];
+	for (const block of blocks) {
+		const cellIndex = block.table?.cellIndex ?? 0;
+		const existing = byCell[cellIndex];
+		byCell[cellIndex] = existing === void 0 ? block.text : `${existing}\n${block.text}`;
+	}
+	return Array.from(byCell, (text) => text ?? "");
+};
+const columnCellTexts = (blocks) => {
+	const byCell = /* @__PURE__ */ new Map();
+	for (const block of blocks) {
+		const table = block.table;
+		if (!table) continue;
+		const key = `${String(table.rowIndex)}:${String(table.cellIndex)}`;
+		const existing = byCell.get(key);
+		byCell.set(key, existing === void 0 ? block.text : `${existing}\n${block.text}`);
+	}
+	return [...byCell.values()];
+};
+/**
+* The paragraph properties that differ, or `null` when they agree. Only the
+* ones a block projection can see and an operation can set: a list level and
+* a paragraph style, the two edits that move no words and are invisible in a
+* text diff.
+*/
+const changedParagraphProperties = (baseBlock, targetBlock) => {
+	const properties = {};
+	if ((baseBlock.styleId ?? null) !== (targetBlock.styleId ?? null)) properties.styleId = targetBlock.styleId ?? null;
+	if (baseBlock.listLevel !== targetBlock.listLevel) properties.listLevel = targetBlock.listLevel ?? null;
+	return Object.keys(properties).length > 0 ? properties : null;
+};
+const locationOf = (story, block) => block.table ? {
+	story,
+	cell: block.table
+} : { story };
+/**
+* Plan one story's comparison, or `null` when it needs more operations than
+* `maxOperations`.
+*/
+const planStoryCompare = ({ story, baseSnapshot, targetSnapshot, maxOperations }) => {
+	const steps = buildSteps({
+		story,
+		baseSnapshot,
+		targetSnapshot
+	});
+	const paragraphMarkPlans = detectParagraphMarkEdits(steps);
+	const consumedSteps = new Set([...paragraphMarkPlans.keys()].map((index) => index + 1));
+	const movesByBaseBlockId = detectMoves(steps, consumedSteps);
+	const moveSourceByTargetBlockId = /* @__PURE__ */ new Map();
+	for (const [baseBlockId, targetBlockId] of movesByBaseBlockId) moveSourceByTargetBlockId.set(targetBlockId, baseBlockId);
+	const anchorIds = nextBaseBlockIdByStep(steps);
+	const changes = [];
+	const operations = [];
+	/**
+	* The anchor everything past the base document's content hangs from: its
+	* last BODY-LEVEL paragraph, which the format guarantees exists because a
+	* table may not be the last child of a body. Anchoring to the last block
+	* instead put the anchor inside a table whenever the story ended with one,
+	* and an insertion anchored there escapes to the table's boundary, where no
+	* paragraph mark can express the break it added.
+	*
+	* The applier orders insertions that resolve to one position by their order
+	* in this array, so the tail is emitted where its step sits rather than
+	* collected and appended — a table and a paragraph both added after the last
+	* base block otherwise come out in operation order, which is not target
+	* order.
+	*/
+	const tailAnchorId = trailingBodyBlockId(baseSnapshot);
+	let operationSequence = 0;
+	const nextOperationId = () => `compare-${++operationSequence}`;
+	/**
+	* The relocation this block belongs to, named so the applier can link the
+	* deletion at the source with the insertion at the destination as
+	* `w:moveFrom` and `w:moveTo` instead of writing two unrelated revisions.
+	*/
+	const moveIdOf = (baseBlockId) => `move-${baseBlockId}`;
+	const pushInsertOperation = (block, anchorId) => {
+		const moveSourceId = moveSourceByTargetBlockId.get(block.id);
+		const shared = {
+			text: block.text,
+			...moveSourceId !== void 0 && { moveId: moveIdOf(moveSourceId) },
+			styleId: block.styleId ?? null,
+			listLevel: block.listLevel ?? null
+		};
+		if (anchorId !== null) {
+			operations.push({
+				id: nextOperationId(),
+				type: "insertBeforeBlock",
+				blockId: anchorId,
+				...shared
+			});
+			return;
+		}
+		if (tailAnchorId === null) return;
+		operations.push({
+			id: nextOperationId(),
+			type: "insertAfterBlock",
+			blockId: tailAnchorId,
+			...shared
+		});
+	};
+	for (const [stepIndex, step] of steps.entries()) {
+		if (consumedSteps.has(stepIndex)) continue;
+		const paragraphMarkPlan = paragraphMarkPlans.get(stepIndex);
+		if (paragraphMarkPlan?.type === "split") {
+			const { baseBlock, targetBlocks: splitInto, offset, separator } = paragraphMarkPlan;
+			changes.push({
+				kind: "split",
+				location: locationOf(story, baseBlock),
+				baseBlockId: baseBlock.id,
+				targetBlockIds: splitInto.map(({ id }) => id),
+				text: baseBlock.text
+			});
+			operations.push({
+				id: nextOperationId(),
+				type: "splitBlock",
+				blockId: baseBlock.id,
+				offset,
+				...separator.length > 0 && { separator }
+			});
+			continue;
+		}
+		if (paragraphMarkPlan?.type === "merge") {
+			const { baseBlocks, targetBlock, separator } = paragraphMarkPlan;
+			changes.push({
+				kind: "merge",
+				location: locationOf(story, baseBlocks[0]),
+				baseBlockIds: baseBlocks.map(({ id }) => id),
+				targetBlockId: targetBlock.id,
+				text: targetBlock.text
+			});
+			operations.push({
+				id: nextOperationId(),
+				type: "mergeBlockWithNext",
+				blockId: baseBlocks[0].id,
+				...separator.length > 0 && { separator }
+			});
+			continue;
+		}
+		switch (step.type) {
+			case "pair": {
+				const { baseBlock, targetBlock } = step;
+				const properties = changedParagraphProperties(baseBlock, targetBlock);
+				if (properties) {
+					changes.push({
+						kind: "paragraph-format",
+						location: locationOf(story, baseBlock),
+						baseBlockId: baseBlock.id,
+						targetBlockId: targetBlock.id,
+						properties
+					});
+					operations.push({
+						id: nextOperationId(),
+						type: "setBlockParagraphProperties",
+						blockId: baseBlock.id,
+						properties
+					});
+				}
+				if (baseBlock.text !== targetBlock.text) {
+					changes.push({
+						kind: "replace",
+						location: locationOf(story, baseBlock),
+						baseBlockId: baseBlock.id,
+						targetBlockId: targetBlock.id,
+						before: baseBlock.text,
+						after: targetBlock.text
+					});
+					operations.push({
+						id: nextOperationId(),
+						type: "replaceBlock",
+						blockId: baseBlock.id,
+						text: targetBlock.text
+					});
+					break;
+				}
+				const segments = inlineFormattingSegments({
+					baseBlock,
+					targetBlock,
+					maxSegments: maxOperations
+				});
+				if (segments === null) return null;
+				if (segments.length === 0) break;
+				changes.push({
+					kind: "format",
+					location: locationOf(story, baseBlock),
+					baseBlockId: baseBlock.id,
+					targetBlockId: targetBlock.id,
+					text: baseBlock.text,
+					ranges: segments
+				});
+				for (const { startOffset, endOffset, formatting } of segments) {
+					const range = createFolioAITextRangeHandle({
+						blockId: baseBlock.id,
+						text: baseBlock.text,
+						startOffset,
+						endOffset
+					});
+					if (!range) panic("An aligned formatting range could not be represented");
+					operations.push({
+						id: nextOperationId(),
+						type: "formatRange",
+						range,
+						formatting
+					});
+				}
+				break;
+			}
+			case "baseOnly": {
+				const targetBlockId = movesByBaseBlockId.get(step.block.id);
+				if (targetBlockId === void 0) changes.push({
+					kind: "delete",
+					location: locationOf(story, step.block),
+					baseBlockId: step.block.id,
+					before: step.block.text
+				});
+				operations.push({
+					id: nextOperationId(),
+					type: "deleteBlock",
+					blockId: step.block.id,
+					...targetBlockId !== void 0 && { moveId: moveIdOf(step.block.id) }
+				});
+				break;
+			}
+			case "targetOnly": {
+				const baseBlockId = moveSourceByTargetBlockId.get(step.block.id);
+				changes.push(baseBlockId === void 0 ? {
+					kind: "insert",
+					location: locationOf(story, step.block),
+					targetBlockId: step.block.id,
+					after: step.block.text
+				} : {
+					kind: "move",
+					location: locationOf(story, step.block),
+					baseBlockId,
+					targetBlockId: step.block.id,
+					text: step.block.text
+				});
+				pushInsertOperation(step.block, anchorIds[stepIndex] ?? null);
+				break;
+			}
+			case "baseRow": {
+				const anchorBlockId = step.blocks[0]?.id;
+				if (anchorBlockId === void 0) panic("A collapsed table row carried no blocks");
+				changes.push({
+					kind: "table-row-delete",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					rowIndex: step.location.rowIndex,
+					cells: rowCellTexts(step.blocks),
+					baseBlockIds: step.blocks.map(({ id }) => id)
+				});
+				operations.push({
+					id: nextOperationId(),
+					type: "deleteTableRow",
+					blockId: anchorBlockId
+				});
+				break;
+			}
+			case "baseColumn": {
+				const anchorBlockId = step.blocks.at(0)?.id;
+				if (anchorBlockId === void 0) panic("A table column carried no blocks");
+				changes.push({
+					kind: "table-column-delete",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					columnIndex: step.columnIndex,
+					cells: columnCellTexts(step.blocks),
+					baseBlockIds: step.blocks.map(({ id }) => id)
+				});
+				operations.push({
+					id: nextOperationId(),
+					type: "deleteTableColumn",
+					blockId: anchorBlockId
+				});
+				break;
+			}
+			case "baseTable": {
+				const anchorBlockId = step.blocks[0]?.id;
+				if (anchorBlockId === void 0) panic("An unpaired table segment carried no blocks");
+				changes.push({
+					kind: "table-delete",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					rows: tableCellTexts(step.blocks),
+					baseBlockIds: step.blocks.map(({ id }) => id)
+				});
+				operations.push({
+					id: nextOperationId(),
+					type: "deleteTable",
+					blockId: anchorBlockId
+				});
+				break;
+			}
+			case "targetTable": {
+				const rows = tableCellTexts(step.blocks);
+				changes.push({
+					kind: "table-insert",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					rows,
+					targetBlockIds: step.blocks.map(({ id }) => id)
+				});
+				const before = anchorIds[stepIndex] ?? null;
+				if (before !== null) {
+					operations.push({
+						id: nextOperationId(),
+						type: "insertTable",
+						blockId: before,
+						position: "before",
+						rows
+					});
+					break;
+				}
+				if (tailAnchorId !== null) operations.push({
+					id: nextOperationId(),
+					type: "insertTable",
+					blockId: tailAnchorId,
+					position: "after",
+					rows
+				});
+				break;
+			}
+			case "targetRow": {
+				const anchor = findRowAnchor(steps, stepIndex);
+				const cells = rowCellTexts(step.blocks);
+				changes.push({
+					kind: "table-row-insert",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					rowIndex: step.location.rowIndex,
+					cells,
+					targetBlockIds: step.blocks.map(({ id }) => id)
+				});
+				if (anchor === null) {
+					for (const block of step.blocks) pushInsertOperation(block, anchorIds[stepIndex] ?? null);
+					break;
+				}
+				operations.push({
+					id: nextOperationId(),
+					type: "insertTableRow",
+					blockId: anchor.blockId,
+					position: anchor.position,
+					cellTexts: cells
+				});
+				break;
+			}
+			case "targetColumn":
+				changes.push({
+					kind: "table-column-insert",
+					location: {
+						story,
+						cell: step.location
+					},
+					tableIndex: step.location.tableIndex,
+					columnIndex: step.columnIndex,
+					cells: columnCellTexts(step.blocks),
+					targetBlockIds: step.blocks.map(({ id }) => id)
+				});
+				operations.push({
+					id: nextOperationId(),
+					type: "insertTableColumn",
+					blockId: step.anchor.blockId,
+					position: step.anchor.position,
+					cellTexts: columnCellTexts(step.blocks)
+				});
+				break;
+			default: panic("Unhandled compare step", { step });
+		}
+		if (operations.length > maxOperations) return null;
+	}
+	return operations.length > maxOperations ? null : {
+		changes,
+		operations
+	};
+};
+//#endregion
+export { planStoryCompare };