@stll/folio-core 0.36.0 → 0.37.0

package/dist/compare/content.js

@@ -0,0 +1,885 @@
+import { WORD_DIFF_GRANULARITIES, createWordDiffSession } from "../ai-edits/word-diff.js";
+import { alignFolioContentStructure, contentBlocksShareContainer, createFolioContentAlignmentWorkSession } from "./content-alignment.js";
+import { inlineFormattingSegments } from "./formatting.js";
+import { Result, TaggedError, panic } from "better-result";
+//#region src/compare/content.ts
+/**
+* Pure comparison of two ordered, representation-neutral content snapshots.
+*
+* Every event carries exact base and revised block tuples. Concatenating the
+* base tuples reconstructs the base snapshot; concatenating the revised tuples
+* reconstructs the revised snapshot. This remains true for moves, paragraph
+* splits/merges, and table-column changes whose cells are not contiguous.
+*/
+/** Hard resource ceilings for one representation-neutral comparison. */
+const FOLIO_CONTENT_COMPARISON_LIMITS = Object.freeze({
+	blocksPerSnapshot: 1e5,
+	changes: 1e4,
+	blockCodeUnits: 1048576,
+	textCodeUnitsPerSnapshot: 8e6,
+	previewRunsPerBlock: 65536,
+	previewRunsPerSnapshot: 1e6,
+	containerDepth: 64,
+	containerEntriesPerSnapshot: 1e6,
+	attributeCodeUnits: 16384,
+	attributeCodeUnitsPerSnapshot: 8e6
+});
+/** Words a one-sided block needs before it may be classified as a move. */
+const MOVE_MINIMUM_WORD_COUNT = 3;
+/** Same-text move candidates retained for one repeated value. */
+const MAX_MOVE_CANDIDATES_PER_TEXT = 64;
+/** Pairwise comparisons allowed for edited-move discovery. */
+const MAX_MOVE_SIMILARITY_COMPARISONS = 2e4;
+/** Map lookups allowed across edited-move similarity scoring. */
+const MAX_MOVE_SIMILARITY_TOKEN_LOOKUPS = 4e6;
+/** Minimum multiset Dice similarity for an edited relocation. */
+const MOVE_SIMILARITY_THRESHOLD = .8;
+/** Bound token material retained for one edited-move candidate. */
+const MAX_MOVE_PROFILE_TOKENS = 16384;
+/** Bound source code units copied into one edited-move token profile. */
+const MAX_MOVE_PROFILE_CODE_UNITS = 1048576;
+var InvalidFolioContentComparisonError = class extends TaggedError("InvalidFolioContentComparisonError") {};
+var FolioContentComparisonLimitError = class extends TaggedError("FolioContentComparisonLimitError") {};
+const createContentComparisonWorkSession = (granularity) => ({
+	alignment: createFolioContentAlignmentWorkSession(),
+	remainingMoveComparisons: MAX_MOVE_SIMILARITY_COMPARISONS,
+	remainingMoveTokenLookups: MAX_MOVE_SIMILARITY_TOKEN_LOOKUPS,
+	diffText: createWordDiffSession({ ...granularity && { granularity } }).diff
+});
+const invalidInput = (input, field, message, blockIndex) => new InvalidFolioContentComparisonError({
+	message,
+	input,
+	field,
+	...blockIndex !== void 0 && { blockIndex }
+});
+const limitExceeded = ({ input, limit, maximum, actual, blockIndex, field }) => new FolioContentComparisonLimitError({
+	message: `The ${input} content exceeds the ${limit} comparison limit.`,
+	input,
+	limit,
+	maximum,
+	actual,
+	...blockIndex !== void 0 && { blockIndex },
+	...field !== void 0 && { field }
+});
+const isFiniteInteger = (value) => typeof value === "number" && Number.isSafeInteger(value);
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasRecordShape = (value) => isRecord(value);
+const PARAGRAPH_ALIGNMENTS = /* @__PURE__ */ new Set([
+	"left",
+	"center",
+	"right",
+	"both",
+	"distribute",
+	"mediumKashida",
+	"highKashida",
+	"lowKashida",
+	"thaiDistribute"
+]);
+const validateRunFormatting = (block, side, blockIndex) => {
+	for (const [runIndex, run] of (block.previewRuns ?? []).entries()) {
+		if (run.directFormatting !== void 0 && !isRecord(run.directFormatting)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].directFormatting`, "Direct inline formatting must be an object.", blockIndex);
+		for (const property of [
+			"bold",
+			"italic",
+			"underline",
+			"strike"
+		]) {
+			if (run[property] !== void 0 && typeof run[property] !== "boolean") return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].${property}`, "Inline boolean formatting must be boolean.", blockIndex);
+			const direct = run.directFormatting?.[property];
+			if (direct !== void 0 && typeof direct !== "boolean") return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].directFormatting.${property}`, "Direct inline boolean formatting must be boolean.", blockIndex);
+		}
+		for (const property of ["fontFamily", "color"]) {
+			const effective = run[property];
+			if (effective !== void 0 && typeof effective !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].${property}`, "Inline string formatting must be a string.", blockIndex);
+			const direct = run.directFormatting?.[property];
+			if (direct !== void 0 && direct !== null && typeof direct !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].directFormatting.${property}`, "Direct inline string formatting must be a string or null.", blockIndex);
+		}
+		if (run.fontSizePt !== void 0 && (!isFiniteNumber(run.fontSizePt) || run.fontSizePt < 0)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].fontSizePt`, "Inline font size must be a non-negative finite number.", blockIndex);
+		const directSize = run.directFormatting?.fontSizePt;
+		if (directSize !== void 0 && directSize !== null && (!isFiniteNumber(directSize) || directSize < 0)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].directFormatting.fontSizePt`, "Direct inline font size must be a non-negative finite number or null.", blockIndex);
+	}
+	return null;
+};
+const validateParagraphFormatting = (block, side, blockIndex) => {
+	for (const property of ["styleId", "displayLabel"]) if (block[property] !== void 0 && typeof block[property] !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].${property}`, "Optional block labels and style ids must be strings.", blockIndex);
+	if (block.headingLevel !== void 0 && (!isFiniteInteger(block.headingLevel) || block.headingLevel < 1)) return invalidInput(side, `blocks[${String(blockIndex)}].headingLevel`, "Heading levels must be positive integers.", blockIndex);
+	if (block.listLevel !== void 0 && (!isFiniteInteger(block.listLevel) || block.listLevel < 0)) return invalidInput(side, `blocks[${String(blockIndex)}].listLevel`, "List levels must be non-negative integers.", blockIndex);
+	if (block.directAlignment !== void 0 && !PARAGRAPH_ALIGNMENTS.has(block.directAlignment)) return invalidInput(side, `blocks[${String(blockIndex)}].directAlignment`, "Paragraph alignment is not recognized.", blockIndex);
+	const spacing = block.directSpacing;
+	if (spacing === void 0) return null;
+	if (!isRecord(spacing)) return invalidInput(side, `blocks[${String(blockIndex)}].directSpacing`, "Direct paragraph spacing must be an object.", blockIndex);
+	for (const property of [
+		"spaceBefore",
+		"spaceAfter",
+		"lineSpacing"
+	]) if (spacing[property] !== void 0 && !isFiniteNumber(spacing[property])) return invalidInput(side, `blocks[${String(blockIndex)}].directSpacing.${property}`, "Paragraph spacing values must be finite numbers.", blockIndex);
+	for (const property of ["beforeAutospacing", "afterAutospacing"]) if (spacing[property] !== void 0 && typeof spacing[property] !== "boolean") return invalidInput(side, `blocks[${String(blockIndex)}].directSpacing.${property}`, "Paragraph auto-spacing values must be boolean.", blockIndex);
+	if (spacing.lineSpacingRule !== void 0 && spacing.lineSpacingRule !== "auto" && spacing.lineSpacingRule !== "exact" && spacing.lineSpacingRule !== "atLeast") return invalidInput(side, `blocks[${String(blockIndex)}].directSpacing.lineSpacingRule`, "Paragraph line-spacing rule is not recognized.", blockIndex);
+	return null;
+};
+const validateTableLocation = (table, side, blockIndex) => {
+	if (!isRecord(table)) return invalidInput(side, `blocks[${String(blockIndex)}].table`, "A table location must be an object.", blockIndex);
+	for (const field of [
+		"outerTableIndex",
+		"tableIndex",
+		"rowIndex",
+		"cellIndex",
+		"gridColumnIndex",
+		"paragraphIndex"
+	]) if (!isFiniteInteger(table[field]) || table[field] < 0) return invalidInput(side, `blocks[${String(blockIndex)}].table.${field}`, "Table indexes must be non-negative integers.", blockIndex);
+	for (const field of ["columnSpan", "rowSpan"]) if (!isFiniteInteger(table[field]) || table[field] < 1) return invalidInput(side, `blocks[${String(blockIndex)}].table.${field}`, "Table spans must be positive integers.", blockIndex);
+	const gridColumnIndex = table["gridColumnIndex"];
+	const columnSpan = table["columnSpan"];
+	const right = typeof gridColumnIndex === "number" && typeof columnSpan === "number" ? gridColumnIndex + columnSpan : NaN;
+	if (!Number.isSafeInteger(right)) return invalidInput(side, `blocks[${String(blockIndex)}].table.columnSpan`, "A table cell's ending grid column must be a safe integer.", blockIndex);
+	const rowIndex = table["rowIndex"];
+	const rowSpan = table["rowSpan"];
+	const bottom = typeof rowIndex === "number" && typeof rowSpan === "number" ? rowIndex + rowSpan : NaN;
+	if (!Number.isSafeInteger(bottom)) return invalidInput(side, `blocks[${String(blockIndex)}].table.rowSpan`, "A table cell's ending row must be a safe integer.", blockIndex);
+	return null;
+};
+const overlappingTableCellBlockIndex = (cells) => {
+	if (cells.length < 2) return null;
+	const columns = [...new Set(cells.flatMap(({ left, right }) => [left, right]))].toSorted((left, right) => left - right);
+	if (columns.length < 2) return null;
+	const columnIndex = new Map(columns.map((column, index) => [column, index]));
+	const intervalCount = columns.length - 1;
+	const maximum = new Int32Array(intervalCount * 4);
+	const pending = new Int32Array(intervalCount * 4);
+	const add = (node, nodeLeft, nodeRight, rangeLeft, rangeRight, amount) => {
+		if (rangeLeft <= nodeLeft && nodeRight <= rangeRight) {
+			maximum[node] = (maximum[node] ?? 0) + amount;
+			pending[node] = (pending[node] ?? 0) + amount;
+			return;
+		}
+		const middle = nodeLeft + Math.floor((nodeRight - nodeLeft) / 2);
+		if (rangeLeft <= middle) add(node * 2, nodeLeft, middle, rangeLeft, rangeRight, amount);
+		if (rangeRight > middle) add(node * 2 + 1, middle + 1, nodeRight, rangeLeft, rangeRight, amount);
+		maximum[node] = (pending[node] ?? 0) + Math.max(maximum[node * 2] ?? 0, maximum[node * 2 + 1] ?? 0);
+	};
+	const events = cells.flatMap((cell) => [{
+		row: cell.top,
+		amount: 1,
+		cell
+	}, {
+		row: cell.bottom,
+		amount: -1,
+		cell
+	}]);
+	events.sort((left, right) => left.row - right.row || left.amount - right.amount || left.cell.left - right.cell.left || left.cell.blockIndex - right.cell.blockIndex);
+	for (const { amount, cell } of events) {
+		const left = columnIndex.get(cell.left);
+		const right = columnIndex.get(cell.right);
+		if (left === void 0 || right === void 0 || left >= right) return panic("A validated table cell has no coordinate-compression interval");
+		add(1, 0, intervalCount - 1, left, right - 1, amount);
+		if (amount > 0 && (maximum[1] ?? 0) > 1) return cell.blockIndex;
+	}
+	return null;
+};
+const chargeAttributeString = ({ value, side, blockIndex, field, usage }) => {
+	if (value === void 0 || value === null) return null;
+	if (value.length > FOLIO_CONTENT_COMPARISON_LIMITS.attributeCodeUnits) return limitExceeded({
+		input: side,
+		limit: "attributeCodeUnits",
+		maximum: FOLIO_CONTENT_COMPARISON_LIMITS.attributeCodeUnits,
+		actual: value.length,
+		blockIndex,
+		field
+	});
+	usage.attributeCodeUnits += value.length;
+	if (usage.attributeCodeUnits > FOLIO_CONTENT_COMPARISON_LIMITS.attributeCodeUnitsPerSnapshot) return limitExceeded({
+		input: side,
+		limit: "attributeCodeUnitsPerSnapshot",
+		maximum: FOLIO_CONTENT_COMPARISON_LIMITS.attributeCodeUnitsPerSnapshot,
+		actual: usage.attributeCodeUnits,
+		blockIndex,
+		field
+	});
+	return null;
+};
+const validateSnapshot = (snapshot, side) => {
+	if (!snapshot || !Array.isArray(snapshot.blocks)) return invalidInput(side, "blocks", "A content snapshot must contain an ordered blocks array.");
+	if (snapshot.blocks.length > FOLIO_CONTENT_COMPARISON_LIMITS.blocksPerSnapshot) return limitExceeded({
+		input: side,
+		limit: "blocksPerSnapshot",
+		maximum: FOLIO_CONTENT_COMPARISON_LIMITS.blocksPerSnapshot,
+		actual: snapshot.blocks.length
+	});
+	const usage = {
+		textCodeUnits: 0,
+		previewRuns: 0,
+		containerEntries: 0,
+		attributeCodeUnits: 0
+	};
+	const ids = /* @__PURE__ */ new Set();
+	const lastCoordinateByTable = /* @__PURE__ */ new Map();
+	const geometryByCell = /* @__PURE__ */ new Map();
+	const cellsByTable = /* @__PURE__ */ new Map();
+	const outerTableByTableIndex = /* @__PURE__ */ new Map();
+	let lastOuterTableIndex = -1;
+	let activeOuterTableIndex = null;
+	for (const [blockIndex, block] of snapshot.blocks.entries()) {
+		if (!hasRecordShape(block)) return invalidInput(side, `blocks[${String(blockIndex)}]`, "Every content block must be an object.", blockIndex);
+		if (typeof block.id !== "string" || block.id.length === 0) return invalidInput(side, `blocks[${String(blockIndex)}].id`, "Every content block needs a non-empty id.", blockIndex);
+		const idLimit = chargeAttributeString({
+			value: block.id,
+			side,
+			blockIndex,
+			field: `blocks[${String(blockIndex)}].id`,
+			usage
+		});
+		if (idLimit) return idLimit;
+		if (ids.has(block.id)) return invalidInput(side, `blocks[${String(blockIndex)}].id`, "Content block ids must be unique within a snapshot.", blockIndex);
+		ids.add(block.id);
+		if (typeof block.kind !== "string" || block.kind.length === 0) return invalidInput(side, `blocks[${String(blockIndex)}].kind`, "Every content block needs a non-empty kind.", blockIndex);
+		const kindLimit = chargeAttributeString({
+			value: block.kind,
+			side,
+			blockIndex,
+			field: `blocks[${String(blockIndex)}].kind`,
+			usage
+		});
+		if (kindLimit) return kindLimit;
+		if (typeof block.text !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].text`, "Content block text must be a string.", blockIndex);
+		if (block.text.length > FOLIO_CONTENT_COMPARISON_LIMITS.blockCodeUnits) return limitExceeded({
+			input: side,
+			limit: "blockCodeUnits",
+			maximum: FOLIO_CONTENT_COMPARISON_LIMITS.blockCodeUnits,
+			actual: block.text.length,
+			blockIndex,
+			field: `blocks[${String(blockIndex)}].text`
+		});
+		usage.textCodeUnits += block.text.length;
+		if (usage.textCodeUnits > FOLIO_CONTENT_COMPARISON_LIMITS.textCodeUnitsPerSnapshot) return limitExceeded({
+			input: side,
+			limit: "textCodeUnitsPerSnapshot",
+			maximum: FOLIO_CONTENT_COMPARISON_LIMITS.textCodeUnitsPerSnapshot,
+			actual: usage.textCodeUnits,
+			blockIndex,
+			field: `blocks[${String(blockIndex)}].text`
+		});
+		if (block.idStability !== void 0 && block.idStability !== "stable" && block.idStability !== "positional") return invalidInput(side, `blocks[${String(blockIndex)}].idStability`, "Block id stability must be stable or positional.", blockIndex);
+		if (block.previewRuns !== void 0) {
+			if (!Array.isArray(block.previewRuns)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns`, "Preview runs must be an array of text runs.", blockIndex);
+			if (block.previewRuns.length > FOLIO_CONTENT_COMPARISON_LIMITS.previewRunsPerBlock) return limitExceeded({
+				input: side,
+				limit: "previewRunsPerBlock",
+				maximum: FOLIO_CONTENT_COMPARISON_LIMITS.previewRunsPerBlock,
+				actual: block.previewRuns.length,
+				blockIndex,
+				field: `blocks[${String(blockIndex)}].previewRuns`
+			});
+			usage.previewRuns += block.previewRuns.length;
+			if (usage.previewRuns > FOLIO_CONTENT_COMPARISON_LIMITS.previewRunsPerSnapshot) return limitExceeded({
+				input: side,
+				limit: "previewRunsPerSnapshot",
+				maximum: FOLIO_CONTENT_COMPARISON_LIMITS.previewRunsPerSnapshot,
+				actual: usage.previewRuns,
+				blockIndex,
+				field: `blocks[${String(blockIndex)}].previewRuns`
+			});
+			let runTextOffset = 0;
+			for (const [runIndex, run] of block.previewRuns.entries()) {
+				if (!hasRecordShape(run) || typeof run.text !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns`, "Preview runs must be an array of text runs.", blockIndex);
+				if (!block.text.startsWith(run.text, runTextOffset)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns`, "Preview-run text must reconstruct the block text exactly.", blockIndex);
+				runTextOffset += run.text.length;
+				for (const property of ["fontFamily", "color"]) for (const [suffix, value] of [[property, run[property]], [`directFormatting.${property}`, run.directFormatting?.[property]]]) {
+					const formattingLimit = chargeAttributeString({
+						value: typeof value === "string" ? value : void 0,
+						side,
+						blockIndex,
+						field: `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].${suffix}`,
+						usage
+					});
+					if (formattingLimit) return formattingLimit;
+				}
+			}
+			if (runTextOffset !== block.text.length) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns`, "Preview-run text must reconstruct the block text exactly.", blockIndex);
+		}
+		const paragraphError = validateParagraphFormatting(block, side, blockIndex);
+		if (paragraphError) return paragraphError;
+		const runError = validateRunFormatting(block, side, blockIndex);
+		if (runError) return runError;
+		for (const property of ["styleId", "displayLabel"]) {
+			const propertyLimit = chargeAttributeString({
+				value: block[property],
+				side,
+				blockIndex,
+				field: `blocks[${String(blockIndex)}].${property}`,
+				usage
+			});
+			if (propertyLimit) return propertyLimit;
+		}
+		if (block.containerPath !== void 0) {
+			if (!Array.isArray(block.containerPath)) return invalidInput(side, `blocks[${String(blockIndex)}].containerPath`, "Container paths require non-empty kind and id values.", blockIndex);
+			if (block.containerPath.length > FOLIO_CONTENT_COMPARISON_LIMITS.containerDepth) return limitExceeded({
+				input: side,
+				limit: "containerDepth",
+				maximum: FOLIO_CONTENT_COMPARISON_LIMITS.containerDepth,
+				actual: block.containerPath.length,
+				blockIndex,
+				field: `blocks[${String(blockIndex)}].containerPath`
+			});
+			usage.containerEntries += block.containerPath.length;
+			if (usage.containerEntries > FOLIO_CONTENT_COMPARISON_LIMITS.containerEntriesPerSnapshot) return limitExceeded({
+				input: side,
+				limit: "containerEntriesPerSnapshot",
+				maximum: FOLIO_CONTENT_COMPARISON_LIMITS.containerEntriesPerSnapshot,
+				actual: usage.containerEntries,
+				blockIndex,
+				field: `blocks[${String(blockIndex)}].containerPath`
+			});
+			for (const [pathIndex, entry] of block.containerPath.entries()) {
+				if (!hasRecordShape(entry) || typeof entry.kind !== "string" || entry.kind.length === 0 || typeof entry.id !== "string" || entry.id.length === 0) return invalidInput(side, `blocks[${String(blockIndex)}].containerPath`, "Container paths require non-empty kind and id values.", blockIndex);
+				for (const property of ["kind", "id"]) {
+					const pathLimit = chargeAttributeString({
+						value: entry[property],
+						side,
+						blockIndex,
+						field: `blocks[${String(blockIndex)}].containerPath[${String(pathIndex)}].${property}`,
+						usage
+					});
+					if (pathLimit) return pathLimit;
+				}
+			}
+		}
+		if (block.table !== void 0) {
+			const error = validateTableLocation(block.table, side, blockIndex);
+			if (error) return error;
+			const table = block.table;
+			if (table.tableIndex < table.outerTableIndex) return invalidInput(side, `blocks[${String(blockIndex)}].table.tableIndex`, "An inner table cannot precede its outer table in document order.", blockIndex);
+			const knownOuterTableIndex = outerTableByTableIndex.get(table.tableIndex);
+			if (knownOuterTableIndex !== void 0 && knownOuterTableIndex !== table.outerTableIndex) return invalidInput(side, `blocks[${String(blockIndex)}].table.tableIndex`, "A table index must identify only one outer table.", blockIndex);
+			outerTableByTableIndex.set(table.tableIndex, table.outerTableIndex);
+			if (table.outerTableIndex < lastOuterTableIndex || table.outerTableIndex === lastOuterTableIndex && activeOuterTableIndex !== table.outerTableIndex) return invalidInput(side, `blocks[${String(blockIndex)}].table`, "Each outer table must occupy one contiguous position in document order.", blockIndex);
+			lastOuterTableIndex = table.outerTableIndex;
+			activeOuterTableIndex = table.outerTableIndex;
+			const tableKey = `${String(table.outerTableIndex)}:${String(table.tableIndex)}`;
+			const cellKey = `${tableKey}:${String(table.rowIndex)}:${String(table.cellIndex)}`;
+			const geometry = [
+				table.gridColumnIndex,
+				table.columnSpan,
+				table.rowSpan
+			];
+			const priorGeometry = geometryByCell.get(cellKey);
+			if (priorGeometry !== void 0 && (geometry[0] !== priorGeometry[0] || geometry[1] !== priorGeometry[1] || geometry[2] !== priorGeometry[2])) return invalidInput(side, `blocks[${String(blockIndex)}].table`, "Every block in one physical table cell must carry the same geometry.", blockIndex);
+			geometryByCell.set(cellKey, geometry);
+			if (priorGeometry === void 0) {
+				const cells = cellsByTable.get(tableKey);
+				const rectangle = {
+					blockIndex,
+					left: table.gridColumnIndex,
+					right: table.gridColumnIndex + table.columnSpan,
+					top: table.rowIndex,
+					bottom: table.rowIndex + table.rowSpan
+				};
+				if (cells) cells.push(rectangle);
+				else cellsByTable.set(tableKey, [rectangle]);
+			}
+			const coordinate = [
+				table.rowIndex,
+				table.cellIndex,
+				table.paragraphIndex
+			];
+			const previous = lastCoordinateByTable.get(tableKey);
+			if (previous && (coordinate[0] < previous[0] || coordinate[0] === previous[0] && coordinate[1] < previous[1] || coordinate[0] === previous[0] && coordinate[1] === previous[1] && coordinate[2] <= previous[2])) return invalidInput(side, `blocks[${String(blockIndex)}].table`, "Blocks in one table must use row-major coordinates.", blockIndex);
+			lastCoordinateByTable.set(tableKey, coordinate);
+		} else activeOuterTableIndex = null;
+	}
+	for (const cells of cellsByTable.values()) {
+		const overlappingBlockIndex = overlappingTableCellBlockIndex(cells);
+		if (overlappingBlockIndex !== null) return invalidInput(side, `blocks[${String(overlappingBlockIndex)}].table`, "Physical table cells must not overlap.", overlappingBlockIndex);
+	}
+	return null;
+};
+const withTextOffsets = (segments) => {
+	const positioned = [];
+	let baseOffset = 0;
+	let revisedOffset = 0;
+	for (const segment of segments) {
+		const baseLength = segment.type === "ins" ? 0 : segment.text.length;
+		const revisedLength = segment.type === "del" ? 0 : segment.text.length;
+		positioned.push({
+			...segment,
+			baseStart: baseOffset,
+			baseEnd: baseOffset + baseLength,
+			revisedStart: revisedOffset,
+			revisedEnd: revisedOffset + revisedLength
+		});
+		baseOffset += baseLength;
+		revisedOffset += revisedLength;
+	}
+	return positioned;
+};
+const paragraphSpacingEqual = (base, revised) => base?.spaceBefore === revised?.spaceBefore && base?.spaceAfter === revised?.spaceAfter && base?.lineSpacing === revised?.lineSpacing && base?.lineSpacingRule === revised?.lineSpacingRule && base?.beforeAutospacing === revised?.beforeAutospacing && base?.afterAutospacing === revised?.afterAutospacing;
+const changedFolioContentParagraphFormatting = (base, revised) => {
+	const patch = {};
+	if ((base.styleId ?? null) !== (revised.styleId ?? null)) patch.styleId = revised.styleId ?? null;
+	if (base.listLevel !== revised.listLevel) patch.listLevel = revised.listLevel ?? null;
+	if (base.directAlignment !== revised.directAlignment) patch.alignment = revised.directAlignment ?? null;
+	if (!paragraphSpacingEqual(base.directSpacing, revised.directSpacing)) patch.spacing = revised.directSpacing ?? null;
+	return Object.keys(patch).length > 0 ? patch : null;
+};
+const changedBlockProperties = (base, revised) => {
+	const changed = [];
+	if (base.kind !== revised.kind) changed.push("kind");
+	if (base.headingLevel !== revised.headingLevel) changed.push("headingLevel");
+	if (base.displayLabel !== revised.displayLabel) changed.push("displayLabel");
+	return changed;
+};
+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;
+};
+const detectFolioContentParagraphMarkPlans = (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 === "revisedOnly") {
+			const separator = separatorBetween(step.baseBlock.text, step.revisedBlock.text, next.block.text);
+			if (separator !== null && contentBlocksShareContainer(step.revisedBlock, next.block)) plans.set(index, {
+				type: "split",
+				baseBlock: step.baseBlock,
+				revisedBlocks: [step.revisedBlock, next.block],
+				offset: step.revisedBlock.text.length,
+				separator
+			});
+			continue;
+		}
+		if (next.type !== "baseOnly") continue;
+		const separator = separatorBetween(step.revisedBlock.text, step.baseBlock.text, next.block.text);
+		if (separator !== null && contentBlocksShareContainer(step.baseBlock, next.block)) plans.set(index, {
+			type: "merge",
+			baseBlocks: [step.baseBlock, next.block],
+			revisedBlock: step.revisedBlock,
+			separator
+		});
+	}
+	return plans;
+};
+const tokenProfile = (text) => {
+	if (text.length > MAX_MOVE_PROFILE_CODE_UNITS) return null;
+	const occurrences = /* @__PURE__ */ new Map();
+	let count = 0;
+	for (const match of text.matchAll(/\S+/gu)) {
+		count++;
+		if (count > MAX_MOVE_PROFILE_TOKENS) return null;
+		const token = match[0];
+		occurrences.set(token, (occurrences.get(token) ?? 0) + 1);
+	}
+	return count >= MOVE_MINIMUM_WORD_COUNT ? {
+		count,
+		occurrences
+	} : null;
+};
+const tokenSimilarity = (base, revised, maximumLookups) => {
+	const [smaller, larger] = base.occurrences.size <= revised.occurrences.size ? [base.occurrences, revised.occurrences] : [revised.occurrences, base.occurrences];
+	if (smaller.size > maximumLookups) return null;
+	let shared = 0;
+	for (const [token, count] of smaller) shared += Math.min(larger.get(token) ?? 0, count);
+	return {
+		similarity: 2 * shared / (base.count + revised.count),
+		lookups: smaller.size
+	};
+};
+const detectFolioContentMoves = ({ steps, consumedStepIndexes, workSession, idStability = (block) => block.idStability ?? "stable" }) => {
+	const stableBaseById = /* @__PURE__ */ new Map();
+	const exactCandidatesByBucket = /* @__PURE__ */ new Map();
+	const similarityCandidatesByBucket = /* @__PURE__ */ new Map();
+	let candidateOrder = 0;
+	for (const [index, step] of steps.entries()) {
+		if (consumedStepIndexes.has(index) || step.type !== "baseOnly") continue;
+		if (idStability(step.block) === "stable") stableBaseById.set(step.block.id, {
+			block: step.block,
+			moveScope: step.moveScope
+		});
+		const profile = tokenProfile(step.block.text);
+		if (!profile) continue;
+		const candidate = {
+			block: step.block,
+			moveScope: step.moveScope,
+			profile,
+			order: candidateOrder++
+		};
+		let candidatesByText = exactCandidatesByBucket.get(step.moveScope.bucket);
+		if (!candidatesByText) {
+			candidatesByText = /* @__PURE__ */ new Map();
+			exactCandidatesByBucket.set(step.moveScope.bucket, candidatesByText);
+		}
+		const queue = candidatesByText.get(step.block.text);
+		if (!queue) candidatesByText.set(step.block.text, [candidate]);
+		else if (queue.length < MAX_MOVE_CANDIDATES_PER_TEXT) queue.push(candidate);
+		let candidatesByGap = similarityCandidatesByBucket.get(step.moveScope.bucket);
+		if (!candidatesByGap) {
+			candidatesByGap = /* @__PURE__ */ new Map();
+			similarityCandidatesByBucket.set(step.moveScope.bucket, candidatesByGap);
+		}
+		let gapCandidates = candidatesByGap.get(step.moveScope.gap);
+		if (!gapCandidates) {
+			gapCandidates = /* @__PURE__ */ new Map();
+			candidatesByGap.set(step.moveScope.gap, gapCandidates);
+		}
+		gapCandidates.set(step.block.id, candidate);
+	}
+	const taken = /* @__PURE__ */ new Set();
+	const takenRevised = /* @__PURE__ */ new Set();
+	const moves = [];
+	const removeSimilarityCandidate = (candidate) => {
+		const candidatesByGap = similarityCandidatesByBucket.get(candidate.moveScope.bucket);
+		const gapCandidates = candidatesByGap?.get(candidate.moveScope.gap);
+		gapCandidates?.delete(candidate.block.id);
+		if (gapCandidates?.size === 0) candidatesByGap?.delete(candidate.moveScope.gap);
+		if (candidatesByGap?.size === 0) similarityCandidatesByBucket.delete(candidate.moveScope.bucket);
+	};
+	for (const [index, step] of steps.entries()) {
+		if (consumedStepIndexes.has(index) || step.type !== "revisedOnly") continue;
+		const candidate = idStability(step.block) === "stable" ? stableBaseById.get(step.block.id) : void 0;
+		if (!candidate || taken.has(candidate.block.id)) continue;
+		taken.add(candidate.block.id);
+		takenRevised.add(step.block.id);
+		removeSimilarityCandidate(candidate);
+		if (candidate.moveScope.bucket === step.moveScope.bucket) moves.push({
+			baseBlock: candidate.block,
+			revisedBlock: step.block
+		});
+	}
+	for (const [index, step] of steps.entries()) {
+		if (consumedStepIndexes.has(index) || step.type !== "revisedOnly" || takenRevised.has(step.block.id)) continue;
+		const exact = (exactCandidatesByBucket.get(step.moveScope.bucket)?.get(step.block.text))?.find((candidate) => !taken.has(candidate.block.id) && candidate.moveScope.gap !== step.moveScope.gap);
+		if (exact) {
+			taken.add(exact.block.id);
+			takenRevised.add(step.block.id);
+			removeSimilarityCandidate(exact);
+			moves.push({
+				baseBlock: exact.block,
+				revisedBlock: step.block
+			});
+		}
+	}
+	for (const [index, step] of steps.entries()) {
+		if (consumedStepIndexes.has(index) || step.type !== "revisedOnly" || takenRevised.has(step.block.id)) continue;
+		const revisedProfile = tokenProfile(step.block.text);
+		if (!revisedProfile) continue;
+		let best = null;
+		const candidatesByGap = similarityCandidatesByBucket.get(step.moveScope.bucket);
+		candidateGroups: for (const [gap, candidates] of candidatesByGap ?? []) {
+			if (gap === step.moveScope.gap) continue;
+			for (const candidate of candidates.values()) {
+				if (workSession.remainingMoveComparisons <= 0) break candidateGroups;
+				workSession.remainingMoveComparisons--;
+				const scored = tokenSimilarity(candidate.profile, revisedProfile, workSession.remainingMoveTokenLookups);
+				if (!scored) continue;
+				workSession.remainingMoveTokenLookups -= scored.lookups;
+				const { similarity } = scored;
+				if (similarity >= MOVE_SIMILARITY_THRESHOLD && (best === null || similarity > best.similarity || similarity === best.similarity && candidate.order < best.candidate.order)) best = {
+					candidate,
+					similarity
+				};
+			}
+		}
+		if (best) {
+			taken.add(best.candidate.block.id);
+			takenRevised.add(step.block.id);
+			removeSimilarityCandidate(best.candidate);
+			moves.push({
+				baseBlock: best.candidate.block,
+				revisedBlock: step.block
+			});
+		}
+	}
+	return moves;
+};
+const structuralChangeForStep = (step, id) => {
+	switch (step.type) {
+		case "baseTable": return {
+			id,
+			type: "table-delete",
+			tableIndex: step.location.tableIndex,
+			baseBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		case "revisedTable": return {
+			id,
+			type: "table-insert",
+			tableIndex: step.location.tableIndex,
+			revisedBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		case "baseRow": return {
+			id,
+			type: "table-row-delete",
+			tableIndex: step.location.tableIndex,
+			rowIndex: step.location.rowIndex,
+			baseBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		case "revisedRow": return {
+			id,
+			type: "table-row-insert",
+			tableIndex: step.location.tableIndex,
+			rowIndex: step.location.rowIndex,
+			revisedBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		case "baseColumn": return {
+			id,
+			type: "table-column-delete",
+			tableIndex: step.location.tableIndex,
+			columnIndex: step.columnIndex,
+			baseBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		case "revisedColumn": return {
+			id,
+			type: "table-column-insert",
+			tableIndex: step.location.tableIndex,
+			columnIndex: step.columnIndex,
+			revisedBlockIds: step.blocks.map(({ id: blockId }) => blockId)
+		};
+		default: return null;
+	}
+};
+const formattingChange = (base, revised, maxRanges) => {
+	const paragraph = changedFolioContentParagraphFormatting(base, revised);
+	const ranges = base.text === revised.text ? inlineFormattingSegments({
+		baseBlock: base,
+		targetBlock: revised,
+		maxSegments: maxRanges
+	}) : [];
+	if (ranges === null) return "limit";
+	return paragraph || ranges.length > 0 ? {
+		...paragraph && { paragraph },
+		ranges
+	} : null;
+};
+const compareAlignedFolioContent = ({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }) => {
+	const paragraphPlans = detectFolioContentParagraphMarkPlans(steps);
+	const consumed = new Set([...paragraphPlans.keys()].map((index) => index + 1));
+	const moves = detectFolioContentMoves({
+		steps,
+		consumedStepIndexes: consumed,
+		workSession,
+		...idStability && { idStability }
+	});
+	const moveByBaseId = new Map(moves.map((move, index) => [move.baseBlock.id, {
+		...move,
+		moveId: index + 1
+	}]));
+	const moveByRevisedId = new Map(moves.map((move, index) => [move.revisedBlock.id, {
+		...move,
+		moveId: index + 1
+	}]));
+	const { diffText } = workSession;
+	const relations = [];
+	const baseRelation = /* @__PURE__ */ new Map();
+	const revisedRelation = /* @__PURE__ */ new Map();
+	const structuralChanges = [];
+	let nextRelationId = 0;
+	let nextStructuralId = 0;
+	let remainingFormattingRanges = maxChanges;
+	let changeCount = 0;
+	const addRelation = (event, relationBaseBlocks, relationRevisedBlocks) => {
+		if (event.type !== "unchanged") {
+			changeCount++;
+			if (changeCount > maxChanges) return false;
+		}
+		const relation = {
+			id: nextRelationId++,
+			baseBlocks: relationBaseBlocks,
+			revisedBlocks: relationRevisedBlocks,
+			event
+		};
+		relations.push(relation);
+		for (const block of relationBaseBlocks) {
+			if (baseRelation.has(block.id)) panic("Content alignment assigned one base block more than once", { blockId: block.id });
+			baseRelation.set(block.id, relation);
+		}
+		for (const block of relationRevisedBlocks) {
+			if (revisedRelation.has(block.id)) panic("Content alignment assigned one revised block more than once", { blockId: block.id });
+			revisedRelation.set(block.id, relation);
+		}
+		return true;
+	};
+	const changeLimitExceeded = () => Result.err(limitExceeded({
+		input: "result",
+		limit: "changes",
+		maximum: maxChanges,
+		actual: maxChanges + 1
+	}));
+	for (const [stepIndex, step] of steps.entries()) {
+		if (consumed.has(stepIndex)) continue;
+		const paragraphPlan = paragraphPlans.get(stepIndex);
+		if (paragraphPlan?.type === "split") {
+			const event = {
+				type: "split",
+				baseBlocks: [paragraphPlan.baseBlock],
+				revisedBlocks: paragraphPlan.revisedBlocks,
+				offset: paragraphPlan.offset,
+				separator: paragraphPlan.separator
+			};
+			if (!addRelation(event, event.baseBlocks, event.revisedBlocks)) return changeLimitExceeded();
+			continue;
+		}
+		if (paragraphPlan?.type === "merge") {
+			const event = {
+				type: "merge",
+				baseBlocks: paragraphPlan.baseBlocks,
+				revisedBlocks: [paragraphPlan.revisedBlock],
+				separator: paragraphPlan.separator
+			};
+			if (!addRelation(event, event.baseBlocks, event.revisedBlocks)) return changeLimitExceeded();
+			continue;
+		}
+		if (step.type === "pair") {
+			const base = step.baseBlock;
+			const revised = step.revisedBlock;
+			const properties = changedBlockProperties(base, revised);
+			const formatting = formattingChange(base, revised, remainingFormattingRanges);
+			if (formatting === "limit") return Result.err(limitExceeded({
+				input: "result",
+				limit: "changes",
+				maximum: maxChanges,
+				actual: maxChanges + 1
+			}));
+			remainingFormattingRanges -= formatting?.ranges.length ?? 0;
+			let event;
+			if (base.text !== revised.text || properties.length > 0) event = {
+				type: "modified",
+				baseBlocks: [base],
+				revisedBlocks: [revised],
+				segments: withTextOffsets(diffText(base.text, revised.text)),
+				changedProperties: properties,
+				...formatting && { formatting }
+			};
+			else if (formatting) event = {
+				type: "formatting",
+				baseBlocks: [base],
+				revisedBlocks: [revised],
+				formatting
+			};
+			else event = {
+				type: "unchanged",
+				baseBlocks: [base],
+				revisedBlocks: [revised]
+			};
+			if (!addRelation(event, [base], [revised])) return changeLimitExceeded();
+			continue;
+		}
+		if (step.type === "baseOnly") {
+			const move = moveByBaseId.get(step.block.id);
+			if (!addRelation(move ? {
+				type: "movedFrom",
+				baseBlocks: [step.block],
+				revisedBlocks: [],
+				moveId: move.moveId
+			} : {
+				type: "deleted",
+				baseBlocks: [step.block],
+				revisedBlocks: []
+			}, [step.block], [])) return changeLimitExceeded();
+			continue;
+		}
+		if (step.type === "revisedOnly") {
+			const move = moveByRevisedId.get(step.block.id);
+			const moveFormatting = move ? formattingChange(move.baseBlock, step.block, remainingFormattingRanges) : null;
+			if (moveFormatting === "limit") return Result.err(limitExceeded({
+				input: "result",
+				limit: "changes",
+				maximum: maxChanges,
+				actual: maxChanges + 1
+			}));
+			remainingFormattingRanges -= moveFormatting?.ranges.length ?? 0;
+			const moveProperties = move ? changedBlockProperties(move.baseBlock, step.block) : [];
+			if (!addRelation(move ? {
+				type: "movedTo",
+				baseBlocks: [],
+				revisedBlocks: [step.block],
+				moveId: move.moveId,
+				baseBlockId: move.baseBlock.id,
+				...move.baseBlock.text !== step.block.text && { segments: withTextOffsets(diffText(move.baseBlock.text, step.block.text)) },
+				...moveProperties.length > 0 && { changedProperties: moveProperties },
+				...moveFormatting && { formatting: moveFormatting }
+			} : {
+				type: "inserted",
+				baseBlocks: [],
+				revisedBlocks: [step.block]
+			}, [], [step.block])) return changeLimitExceeded();
+			continue;
+		}
+		const structural = structuralChangeForStep(step, ++nextStructuralId);
+		if (!structural) return panic("Unhandled content alignment step", { step });
+		structuralChanges.push(structural);
+		if ("baseBlockIds" in structural) {
+			for (const block of step.blocks) if (!addRelation({
+				type: "deleted",
+				baseBlocks: [block],
+				revisedBlocks: [],
+				structuralChangeId: structural.id
+			}, [block], [])) return changeLimitExceeded();
+		} else for (const block of step.blocks) if (!addRelation({
+			type: "inserted",
+			baseBlocks: [],
+			revisedBlocks: [block],
+			structuralChangeId: structural.id
+		}, [], [block])) return changeLimitExceeded();
+	}
+	const ordered = [];
+	const emitted = /* @__PURE__ */ new Set();
+	let baseIndex = 0;
+	let revisedIndex = 0;
+	while (baseIndex < baseBlocks.length || revisedIndex < revisedBlocks.length) {
+		const base = baseBlocks[baseIndex];
+		const revised = revisedBlocks[revisedIndex];
+		const fromBase = base ? baseRelation.get(base.id) : void 0;
+		const fromRevised = revised ? revisedRelation.get(revised.id) : void 0;
+		if (fromBase && emitted.has(fromBase.id)) {
+			baseIndex++;
+			continue;
+		}
+		if (fromRevised && emitted.has(fromRevised.id)) {
+			revisedIndex++;
+			continue;
+		}
+		let relation;
+		if (fromBase && fromRevised && fromBase.id === fromRevised.id) relation = fromBase;
+		else if (fromBase?.revisedBlocks.length === 0) relation = fromBase;
+		else if (fromRevised?.baseBlocks.length === 0) relation = fromRevised;
+		if (!relation) return panic("Content alignment did not produce one monotone projection", {
+			baseBlockId: base?.id,
+			revisedBlockId: revised?.id
+		});
+		emitted.add(relation.id);
+		ordered.push(relation.event);
+		baseIndex += relation.baseBlocks.length;
+		revisedIndex += relation.revisedBlocks.length;
+	}
+	if (emitted.size !== relations.length) return panic("Content alignment left relations outside the ordered projection");
+	return Result.ok({
+		events: ordered,
+		structuralChanges
+	});
+};
+/** Compare two representation-neutral ordered content snapshots. */
+const compareContent = (options) => {
+	if (!isRecord(options)) return Result.err(invalidInput("options", "options", "Comparison options must be an object."));
+	const { base, revised, granularity } = options;
+	if (granularity !== void 0 && !WORD_DIFF_GRANULARITIES.some((candidate) => candidate === granularity)) return Result.err(invalidInput("options", "granularity", "Comparison granularity must be word or character."));
+	const baseError = validateSnapshot(base, "base");
+	if (baseError) return Result.err(baseError);
+	const revisedError = validateSnapshot(revised, "revised");
+	if (revisedError) return Result.err(revisedError);
+	const workSession = createContentComparisonWorkSession(granularity);
+	const steps = alignFolioContentStructure({
+		baseBlocks: base.blocks,
+		revisedBlocks: revised.blocks,
+		workSession: workSession.alignment
+	});
+	return compareAlignedFolioContent({
+		baseBlocks: base.blocks,
+		revisedBlocks: revised.blocks,
+		steps,
+		workSession,
+		maxChanges: FOLIO_CONTENT_COMPARISON_LIMITS.changes
+	});
+};
+//#endregion
+export { FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentComparisonLimitError, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };