@stll/folio-core 0.48.0 → 0.49.0

package/dist/ai-edits/apply.js

@@ -3,6 +3,7 @@ import { formattingEquals } from "../docx/runConsolidator.js";
 import { expectParagraphAttrs, expectRunPropertyChangeMarkAttrs } from "../prosemirror/attrs/index.js";
 import { hasSerializableParagraphPropertyChange, paragraphPropertiesSnapshot } from "../prosemirror/commands/propertyChangeScope.js";
 import { addedBreakCarrierBefore, finalParagraphsOf, paragraphEndsItsContainer } from "../prosemirror/containerFinalParagraph.js";
+import { encloseWholeControls } from "../prosemirror/contentControlRevisions.js";
 import { requestDeterministicParaIds } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
 import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
 import { CLEARED_LIST_RENDERING_ATTRS } from "../prosemirror/listMarker.js";
@@ -12,7 +13,7 @@ import { directParagraphIndentation, paragraphIndentationAttrPatch, paragraphInd
 import { directParagraphSpacing, paragraphSpacingAttrPatch, paragraphSpacingEqual, paragraphSpacingFromFormatting, withDirectParagraphSpacing } from "../prosemirror/paragraphSpacing.js";
 import { getDocumentNumbering } from "../prosemirror/plugins/documentNumbering.js";
 import { getDocumentStyleResolver } from "../prosemirror/plugins/documentStyles.js";
-import { addCarriedMarks, annotatedReplacement, hasReplacedAnnotations, inheritedReplacementMarks, surveyReplacedAnnotations } from "../prosemirror/replacedAnnotations.js";
+import { NON_INCLUSIVE_MARK_DISPOSITION, addCarriedMarks, annotatedReplacement, hasReplacedAnnotations, inheritedReplacementMarks, surveyReplacedAnnotations } from "../prosemirror/replacedAnnotations.js";
 import { applyMarksToRunFormattingRepresentation, runFormattingInlineControlNodeName, selectRunFormattingCarrierRepresentations } from "../prosemirror/runFormattingInlineCarriers.js";
 import { readAuthoredRunFormatting, reconcileRunFormattingMarks } from "../prosemirror/runFormattingReconciliation.js";
 import { paragraphRunStyleContext, paragraphRunStyleContextAt } from "../prosemirror/runStyleFormatting.js";
@@ -22,6 +23,7 @@ import { getFolioParaIdFromBlockId } from "../types/block-id.js";
 import { stripBlockIdentityAttrs } from "./block-identity.js";
 import { buildCleanBlockText, resolveCleanTextRange } from "./clean-text.js";
 import { hasInlineEmphasis, parseInlineEmphasisRuns, stripInlineEmphasisMarkers } from "./inline-emphasis.js";
+import { applyTextChanges, changesFromSegments, planTextChanges, widenChangesToAtomicSpans } from "./minimal-replacement.js";
 import { hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isHiddenTableRow, normalizeFolioAIBlockText } from "./snapshot.js";
 import { mergeTableRectangle, mergeTrackedVerticalTableCells, splitTableRectangle, splitTrackedVerticalTableCell } from "./table-cell-mutations.js";
 import { planTableMutations } from "./table-mutation-plan.js";
@@ -612,7 +614,14 @@ const clearReplacementBackground = ({ tr, schema, from, to, mode, replacementBac
 		...styleResolver !== void 0 ? { styleResolver } : {}
 	});
 };
-const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, revisionIdSeed, author, date, initials, suggestionId = null, styleResolver }) => {
+const applyTrackedInlineFormatting = ({ from, to, ...options }) => applyTrackedInlineFormattingToRanges({
+	...options,
+	ranges: [{
+		from,
+		to
+	}]
+});
+const applyTrackedInlineFormattingToRanges = ({ tr, schema, doc = tr.doc, ranges, formatting, revisionIdSeed, author, date, initials, suggestionId = null, styleResolver }) => {
 	const propertyChangeType = schema.marks["runPropertyChange"];
 	if (!propertyChangeType) return {
 		type: "applied",
@@ -622,11 +631,11 @@ const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, r
 	};
 	const segments = [];
 	let hasPendingRunPropertyChange = false;
-	const representations = selectRunFormattingCarrierRepresentations({
+	const representations = ranges.flatMap(({ from, to }) => selectRunFormattingCarrierRepresentations({
 		doc,
 		from,
 		to
-	});
+	}));
 	for (const representation of representations) {
 		const { node } = representation;
 		const styleContext = paragraphRunStyleContextAt({
@@ -717,36 +726,17 @@ const applyTrackedInlineFormatting = ({ tr, schema, doc, from, to, formatting, r
 * `Date.now()` seed per applyAIEditOperations call would collide
 * across batches that fire within the same millisecond (the panel's
 * Accept-all loop does exactly that — multiple calls in tight
-* succession). Reserving a contiguous range up front guarantees
-* uniqueness across overlapping calls in the same JS realm.
+* succession).
+*
+* A batch without a revision stamp allocates from it as it writes and claims
+* each operation's ids once they are written, rather than reserving a guess
+* up front: how many revisions an operation records is known only once it has
+* recorded them (clearing a background records one run-property change per
+* carrier). The claim also comes before anything that may start another
+* batch, a comment-id callback or the dispatch, so batches in one realm never
+* share an id and follow one another without a gap.
 */
 let revisionIdCursor = Date.now() * 1e3;
-const nextRevisionSeed = (revisionIdCount) => {
-	const start = revisionIdCursor;
-	revisionIdCursor += Math.max(revisionIdCount, 1);
-	return start;
-};
-/**
-* Ids one resolved operation may allocate from the shared revision-id range
-* reserved by `nextRevisionSeed`. Most operation types allocate at most
-* three (delete + insert + background-format clearing); reserving four per
-* operation is a safe cushion above that. A multi-paragraph
-* `insertAfterBlock` / `insertBeforeBlock` (`text` split on line breaks,
-* see `splitInsertParagraphTexts`) allocates one id per paragraph in
-* tracked-changes mode plus one for each paragraph MARK it brings, so it
-* needs more than four once split into more than two paragraphs. Rotating a
-* terminal run can add one paragraph-property revision per inserted paragraph;
-* reserving less than that would let a later `nextRevisionSeed` call reuse an
-* id this operation already stamped on the document.
-*/
-const REVISION_IDS_PER_OPERATION = 4;
-const estimateRevisionIdReservation = (item) => {
-	if (item.operation.type === "insertAfterBlock" || item.operation.type === "insertBeforeBlock") {
-		const paragraphCount = item.insertTexts?.length ?? 1;
-		return Math.max(paragraphCount * 3, REVISION_IDS_PER_OPERATION);
-	}
-	return REVISION_IDS_PER_OPERATION;
-};
 /**
 * Walk the live doc once and bucket every textblock by its
 * normalised text hash. Resolution then maps each snapshot anchor
@@ -1404,9 +1394,19 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 		});
 	}
 	let tr = view.state.tr;
-	const revisionIdReservation = executableResolved.reduce((total, item) => total + estimateRevisionIdReservation(item), 0);
 	const ownsSharedRevisionIdCursor = revisionIdSeed === void 0 && revisionStamp === void 0;
-	let revisionSeed = revisionIdSeed ?? revisionStamp?.idSeed ?? nextRevisionSeed(revisionIdReservation);
+	let revisionSeed = revisionIdSeed ?? revisionStamp?.idSeed ?? revisionIdCursor;
+	/**
+	* Claim the shared ids below `nextRevisionId` for this batch. A seeded or
+	* stamped batch allocates from its own range and claims nothing.
+	*/
+	const claimSharedRevisionIds = (nextRevisionId) => {
+		if (ownsSharedRevisionIdCursor) revisionIdCursor = Math.max(revisionIdCursor, nextRevisionId);
+	};
+	/** Continue past any shared id a batch the host started meanwhile claimed. */
+	const continueSharedRevisionIds = () => {
+		if (ownsSharedRevisionIdCursor) revisionSeed = Math.max(revisionSeed, revisionIdCursor);
+	};
 	const date = revisionStamp?.date ?? (/* @__PURE__ */ new Date()).toISOString();
 	const insertedColumnCounts = /* @__PURE__ */ new Map();
 	const executionOrder = executableResolved.toSorted((left, right) => {
@@ -1437,6 +1437,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 	for (let executionIndex = 0; executionIndex < executionOrder.length; executionIndex++) {
 		const item = executionOrder[executionIndex];
 		if (!item) panic("The operation execution index exceeded the resolved plan", { executionIndex });
+		continueSharedRevisionIds();
 		if (mode === "tracked-changes" && writesParagraphPropertyChange(item)) {
 			const livePosition = tr.mapping.map(item.blockFrom);
 			const liveBlock = tr.doc.nodeAt(livePosition) ?? item.blockNode;
@@ -1475,6 +1476,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 						numbering
 					});
 					revisionSeed = built.nextRevisionId;
+					claimSharedRevisionIds(revisionSeed);
 					nodeGroups.push(built.nodes);
 					runApplied.push({
 						id: insertion.operation.id,
@@ -1522,9 +1524,58 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 		switch (item.operation.type) {
 			case "replaceInBlock":
 			case "replaceRange": {
+				if (mode === "direct" && !hasInlineEmphasis(item.operation.replace)) {
+					const minimal = applyMinimalDirectReplacement({
+						tr,
+						item,
+						replacement: item.operation.replace,
+						commentMark,
+						replacementBackground,
+						...styleResolver !== void 0 ? { styleResolver } : {}
+					});
+					if (minimal !== null) {
+						tr = minimal;
+						break;
+					}
+				}
 				const revisionIdDelete = operationRevisionSeed;
 				const revisionIdInsert = producesTrackedChanges ? operationRevisionSeed + 1 : operationRevisionSeed;
 				const revisionIdBackgroundSeed = producesTrackedChanges ? operationRevisionSeed + 2 : operationRevisionSeed;
+				if (producesTrackedChanges) {
+					const tracked = applyMinimalTrackedReplacement({
+						tr,
+						item,
+						replacement: stripInlineEmphasisMarkers(item.operation.replace),
+						commentMark,
+						replacementBackground,
+						...styleResolver !== void 0 ? { styleResolver } : {},
+						diffText,
+						revisionIdDelete,
+						revisionIdInsert,
+						revisionIdBackgroundSeed,
+						author,
+						date,
+						initials,
+						suggestionId
+					});
+					if (tracked?.type === "pendingRunPropertyChange") {
+						skipped.push({
+							id: item.operation.id,
+							reason: tracked.type
+						});
+						continue;
+					}
+					if (tracked) {
+						tr = tracked.transaction;
+						operationRevisionSeed = tracked.nextRevisionId;
+						appliedRevisionIds = [
+							revisionIdDelete,
+							revisionIdInsert,
+							...tracked.backgroundRevisionIds
+						];
+						break;
+					}
+				}
 				const stepsBeforeBackgroundClear = tr.steps.length;
 				const backgroundResult = clearReplacementBackground({
 					tr,
@@ -1560,8 +1611,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					revisionIdInsert,
 					commentMark,
 					suggestionId,
-					initials,
-					diffText
+					initials
 				});
 				if (producesTrackedChanges) appliedRevisionIds = [
 					revisionIdDelete,
@@ -1652,7 +1702,44 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 				}
 				let clearedBackground = false;
 				let backgroundRevisionIds = [];
-				if (changesText) {
+				const minimal = changesText && mode === "direct" ? applyMinimalDirectReplacement({
+					tr,
+					item,
+					replacement: item.operation.text,
+					commentMark,
+					replacementBackground,
+					...styleResolver !== void 0 ? { styleResolver } : {}
+				}) : null;
+				const tracked = changesText && producesTrackedChanges ? applyMinimalTrackedReplacement({
+					tr,
+					item,
+					replacement: stripInlineEmphasisMarkers(item.operation.text),
+					commentMark,
+					replacementBackground,
+					...styleResolver !== void 0 ? { styleResolver } : {},
+					diffText,
+					revisionIdDelete,
+					revisionIdInsert,
+					revisionIdBackgroundSeed,
+					author,
+					date,
+					initials,
+					suggestionId
+				}) : null;
+				if (tracked?.type === "pendingRunPropertyChange") {
+					skipped.push({
+						id: item.operation.id,
+						reason: tracked.type
+					});
+					continue;
+				}
+				if (minimal !== null) tr = minimal;
+				else if (tracked !== null) {
+					tr = tracked.transaction;
+					operationRevisionSeed = tracked.nextRevisionId;
+					clearedBackground = tracked.backgroundRevisionIds.length > 0;
+					backgroundRevisionIds = tracked.backgroundRevisionIds;
+				} else if (changesText) {
 					const stepsBeforeBackgroundClear = tr.steps.length;
 					const backgroundResult = clearReplacementBackground({
 						tr,
@@ -1689,8 +1776,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 						revisionIdInsert,
 						commentMark,
 						suggestionId,
-						initials,
-						diffText
+						initials
 					});
 				}
 				const allocateStyleRevisionInfo = () => ({
@@ -1993,6 +2079,12 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 					tr = tr.addMark(item.from, item.to, deletionMark);
 					const atomRanges = undeletedContentAtomRanges(tr, item.blockFrom);
 					for (const { from, to } of atomRanges) tr = tr.addMark(from, to, deletionMark);
+					encloseWholeControls({
+						tr,
+						from: item.blockFrom,
+						to: item.blockTo,
+						revisionId
+					});
 					const inlineRevisionApplied = item.from < item.to || atomRanges.length > 0;
 					appliedRevisionIds = inlineRevisionApplied ? [revisionId] : [];
 					const markPosition = tr.mapping.map(item.blockFrom);
@@ -2263,6 +2355,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 				operationId: item.operation.id,
 				operationType: item.operation.type
 			});
+			claimSharedRevisionIds(operationRevisionSeed);
 			committedCommentId = allocateCommittedCommentId(item.commentText);
 			tr = commitProvisionalComment({
 				tr,
@@ -2272,6 +2365,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 			});
 		}
 		revisionSeed = operationRevisionSeed;
+		claimSharedRevisionIds(revisionSeed);
 		applied.push({
 			id: item.operation.id,
 			...committedCommentId !== void 0 && { commentId: committedCommentId },
@@ -2285,6 +2379,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 	if (tr.docChanged) {
 		const batchRevisionIds = new Set(applied.flatMap(({ revisionIds }) => revisionIds ?? []));
 		tr = withoutRevisionsOnZeroWidthAnchors(tr, batchRevisionIds);
+		continueSharedRevisionIds();
 		const rotated = withRotatedAddedFinalBreaks({
 			tr,
 			batchRevisionIds,
@@ -2309,7 +2404,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 				revisionIds: [...receipt.revisionIds, revisionId]
 			};
 		}
-		if (ownsSharedRevisionIdCursor) revisionIdCursor = Math.max(revisionIdCursor, revisionSeed);
+		claimSharedRevisionIds(revisionSeed);
 		if (revisionStamp) requestDeterministicParaIds(tr, `${revisionStamp.date}:${String(revisionStamp.idSeed)}`);
 		view.dispatch(tr);
 	}
@@ -2389,7 +2484,7 @@ const insertCleanText = ({ tr, from, to, text, standsInFor }) => {
 		end: start + contentSize
 	};
 };
-const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete, revisionIdInsert, commentMark, suggestionId = null, initials, diffText }) => {
+const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete, revisionIdInsert, commentMark, suggestionId = null, initials }) => {
 	let nextTr = tr;
 	const replacement = stripInlineEmphasisMarkers((() => {
 		if (item.operation.type === "replaceInBlock" || item.operation.type === "replaceRange") return item.operation.replace;
@@ -2435,86 +2530,6 @@ const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete,
 		...initialsAttr,
 		...suggestionAttrs
 	};
-	const cleanBlock = item.blockNode.content.size === item.blockNode.textContent.length ? buildCleanBlockText(item.blockNode, item.blockFrom) : null;
-	let sourceText = null;
-	let sourceCleanStart = 0;
-	if (cleanBlock !== null) {
-		if (item.operation.type === "replaceInBlock") {
-			sourceText = item.operation.find;
-			sourceCleanStart = cleanBlock.text.indexOf(item.operation.find);
-			if (sourceCleanStart === -1) sourceText = null;
-		} else if (item.operation.type === "replaceRange") {
-			sourceCleanStart = item.operation.range.startOffset;
-			sourceText = cleanBlock.text.slice(sourceCleanStart, item.operation.range.endOffset);
-		} else if (item.operation.type === "replaceBlock") {
-			sourceText = cleanBlock.text;
-			sourceCleanStart = 0;
-		}
-	}
-	if (sourceText !== null && cleanBlock !== null) {
-		const segments = diffText(sourceText, replacement);
-		const offsets = cleanBlock.offsets;
-		const offsetAt = (cleanOffset) => offsets[cleanOffset] ?? null;
-		const steps = [];
-		let cursor = 0;
-		let allPositionsResolved = true;
-		for (const seg of segments) {
-			if (seg.type === "equal") {
-				cursor += seg.text.length;
-				continue;
-			}
-			if (seg.type === "del") {
-				const pmFrom = offsetAt(sourceCleanStart + cursor);
-				const pmTo = offsetAt(sourceCleanStart + cursor + seg.text.length);
-				if (pmFrom === null || pmTo === null) {
-					allPositionsResolved = false;
-					break;
-				}
-				steps.push({
-					kind: "del",
-					from: pmFrom,
-					to: pmTo
-				});
-				cursor += seg.text.length;
-				continue;
-			}
-			const pmAt = offsetAt(sourceCleanStart + cursor);
-			if (pmAt === null) {
-				allPositionsResolved = false;
-				break;
-			}
-			steps.push({
-				kind: "ins",
-				at: pmAt,
-				text: seg.text
-			});
-		}
-		if (allPositionsResolved) {
-			for (const step of steps.toReversed()) {
-				if (step.kind === "del" && deletionType) {
-					nextTr = nextTr.addMark(step.from, step.to, deletionType.create(delAttrs));
-					if (commentMark) nextTr = nextTr.addMark(step.from, step.to, commentMark);
-					continue;
-				}
-				if (step.kind === "ins" && insertionType) {
-					const inserted = insertCleanText({
-						tr: nextTr,
-						from: step.at,
-						to: step.at,
-						text: step.text,
-						standsInFor: {
-							from: item.from,
-							to: item.to
-						}
-					});
-					nextTr = inserted.transaction;
-					nextTr = nextTr.addMark(inserted.start, inserted.end, insertionType.create(insAttrs));
-					if (commentMark) nextTr = nextTr.addMark(inserted.start, inserted.end, commentMark);
-				}
-			}
-			return nextTr;
-		}
-	}
 	if (replacement.length > 0 && insertionType) {
 		const inserted = insertCleanText({
 			tr: nextTr,
@@ -2536,6 +2551,435 @@ const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete,
 	}
 	return nextTr;
 };
+/**
+* The clean-text span a text replacement matched: where it starts in the
+* block's clean text and what it says. `null` when the operation does not
+* replace text or its match is no longer in the block.
+*/
+const replacedCleanSpan = (item, cleanBlock) => {
+	switch (item.operation.type) {
+		case "replaceInBlock": {
+			const start = cleanBlock.text.indexOf(item.operation.find);
+			return start === -1 ? null : {
+				start,
+				text: item.operation.find
+			};
+		}
+		case "replaceRange": {
+			const { startOffset, endOffset } = item.operation.range;
+			return {
+				start: startOffset,
+				text: cleanBlock.text.slice(startOffset, endOffset)
+			};
+		}
+		case "replaceBlock": return {
+			start: 0,
+			text: cleanBlock.text
+		};
+		default: return null;
+	}
+};
+const BACKGROUND_MARK_NAMES = /* @__PURE__ */ new Set(["highlight", "runShading"]);
+/**
+* Formatting, as opposed to a mark naming something outside the text or
+* describing one character (see `NON_INCLUSIVE_MARK_DISPOSITION`).
+*/
+const isFormattingMark = (mark) => mark.type.spec.inclusive !== false;
+const isCarriedMark = (mark) => NON_INCLUSIVE_MARK_DISPOSITION[mark.type.name] === "carry";
+/**
+* Map a text replacement's changes onto the document; `minimal-replacement.ts`
+* states the contract. `null` when the matched span cannot be mapped onto the
+* document character by character, or the changes do not produce the
+* replacement.
+*/
+const planDocumentReplacement = ({ doc, item, replacement, planChanges }) => {
+	const cleanBlock = buildCleanBlockText(item.blockNode, item.blockFrom);
+	const span = replacedCleanSpan(item, cleanBlock);
+	if (span === null) return null;
+	const spanStart = span.start;
+	const spanEnd = span.start + span.text.length;
+	const atomicSpans = cleanBlock.structuralBoundaries.flatMap((boundary) => boundary.type === "field" ? [{
+		offset: boundary.offset - spanStart,
+		length: boundary.length
+	}] : []);
+	const changes = widenChangesToAtomicSpans(span.text, planChanges(span.text), atomicSpans);
+	if (applyTextChanges(span.text, changes) !== replacement) return null;
+	const unitAt = (index) => {
+		const from = cleanBlock.offsets[index];
+		const node = from === void 0 ? null : doc.nodeAt(from);
+		if (from === void 0 || !node) return null;
+		return {
+			from,
+			to: node.isText ? from + 1 : from + node.nodeSize
+		};
+	};
+	const matchedFrom = item.from;
+	const matchedTo = item.to;
+	const holdsMatch = (start, end) => matchedFrom >= start && matchedTo <= end;
+	const climbAfter = (position) => {
+		let at = position;
+		for (let $at = doc.resolve(at);; $at = doc.resolve(at)) {
+			if (!$at.parent.isInline || at !== $at.end() || holdsMatch($at.start(), $at.end())) return at;
+			at = $at.after();
+		}
+	};
+	const climbBefore = (position) => {
+		let at = position;
+		for (let $at = doc.resolve(at);; $at = doc.resolve(at)) {
+			if (!$at.parent.isInline || at !== $at.start() || holdsMatch($at.start(), $at.end())) return at;
+			at = $at.before();
+		}
+	};
+	const isNoteReference = (index) => {
+		const unit = unitAt(index);
+		return (unit === null ? null : doc.nodeAt(unit.from))?.marks.some((mark) => mark.type.name === "footnoteRef") ?? false;
+	};
+	const formattingSourceBefore = (index) => {
+		let source = index;
+		while (source >= 0 && isNoteReference(source)) source--;
+		return source;
+	};
+	const formattingSourceAfter = (index) => {
+		let source = index;
+		while (source < spanEnd && isNoteReference(source)) source++;
+		return source;
+	};
+	const replacementStyleSource = (change) => {
+		const first = spanStart + change.start;
+		const source = formattingSourceAfter(first);
+		return unitAt(source < spanStart + change.end ? source : first);
+	};
+	const matchCarried = (() => {
+		let carried = null;
+		for (let index = spanStart; index < spanEnd; index++) {
+			const unit = unitAt(index);
+			const marks = (unit === null ? null : doc.nodeAt(unit.from))?.marks ?? [];
+			carried = (carried ?? marks.filter(isCarriedMark)).filter((mark) => mark.isInSet(marks));
+			if (carried.length === 0) break;
+		}
+		return carried ?? [];
+	})();
+	const planned = [];
+	for (const change of changes) {
+		const pieces = [];
+		for (let index = spanStart + change.start; index < spanStart + change.end; index++) {
+			const unit = unitAt(index);
+			if (unit === null) return null;
+			const last = pieces.at(-1);
+			if (last !== void 0 && unit.from < last.to) continue;
+			if (last !== void 0 && last.to === unit.from) last.to = unit.to;
+			else pieces.push({ ...unit });
+		}
+		if (pieces.length > 0) {
+			planned.push({
+				change,
+				pieces,
+				text: change.text
+			});
+			continue;
+		}
+		const at = spanStart + change.start;
+		if (span.text.length === 0) {
+			planned.push({
+				change,
+				pieces,
+				text: change.text,
+				insertion: {
+					at: matchedFrom,
+					marks: (current) => current.resolve(matchedFrom).marks()
+				}
+			});
+			continue;
+		}
+		if (at > spanStart) {
+			const previous = unitAt(at - 1);
+			if (previous === null) return null;
+			const styleSource = unitAt(formattingSourceBefore(at - 1));
+			planned.push({
+				change,
+				pieces,
+				text: change.text,
+				insertion: {
+					at: climbAfter(previous.to),
+					marks: (current) => addCarriedMarks(styleSource === null ? [] : current.resolve(styleSource.to).marks(), matchCarried)
+				}
+			});
+			continue;
+		}
+		const first = unitAt(at);
+		if (first === null) return null;
+		const styleSource = unitAt(formattingSourceAfter(at));
+		planned.push({
+			change,
+			pieces,
+			text: change.text,
+			insertion: {
+				at: climbBefore(first.from),
+				marks: (current) => addCarriedMarks(styleSource === null ? [] : (current.nodeAt(styleSource.from)?.marks ?? []).filter(isFormattingMark), matchCarried)
+			}
+		});
+	}
+	return {
+		changes,
+		planned,
+		spanStart,
+		spanEnd,
+		matchedFrom,
+		matchedTo,
+		unitAt,
+		replacementStyleSource
+	};
+};
+/**
+* Apply a direct-mode text replacement as the difference between the matched
+* text and its replacement; `minimal-replacement.ts` states the contract.
+*
+* Returns `null`, before touching the transaction, when the matched span
+* cannot be mapped onto the document character by character. The caller then
+* replaces the matched span whole, as it always did.
+*/
+const applyMinimalDirectReplacement = ({ tr, item, replacement, commentMark, replacementBackground, styleResolver }) => {
+	const plan = planDocumentReplacement({
+		doc: tr.doc,
+		item,
+		replacement,
+		planChanges: (source) => planTextChanges(source, replacement)
+	});
+	if (plan === null || plan.changes.length === 0) return null;
+	const { planned, matchedFrom, matchedTo } = plan;
+	let nextTr = tr;
+	if (replacementBackground === "clear") nextTr = clearTouchedBackground({
+		tr: nextTr,
+		ranges: unitRanges(touchedBackgroundIndices({
+			doc: nextTr.doc,
+			plan
+		}), plan.unitAt),
+		...styleResolver !== void 0 ? { styleResolver } : {}
+	});
+	const stepsBefore = nextTr.steps.length;
+	const written = [];
+	const schema = nextTr.doc.type.schema;
+	for (const change of planned.toReversed()) {
+		if (change.insertion !== void 0) {
+			const { at, marks } = change.insertion;
+			nextTr = nextTr.insert(at, cleanTextInlineNodes({
+				schema,
+				text: change.text,
+				marks: marks(nextTr.doc)
+			}));
+			written.push({
+				from: at,
+				to: at + change.text.length,
+				step: nextTr.steps.length
+			});
+			continue;
+		}
+		const [first, ...rest] = change.pieces;
+		if (first === void 0) continue;
+		const stepsBeforeWrite = nextTr.steps.length;
+		if (change.text.length > 0) {
+			const replaced = insertCleanText({
+				tr: nextTr,
+				from: first.from,
+				to: first.to,
+				text: change.text,
+				standsInFor: {
+					from: first.from,
+					to: rest.at(-1)?.to ?? first.to
+				}
+			});
+			nextTr = replaced.transaction;
+			written.push({
+				from: replaced.start,
+				to: replaced.end,
+				step: nextTr.steps.length
+			});
+		} else nextTr = nextTr.delete(first.from, first.to);
+		const afterWrite = nextTr.mapping.slice(stepsBeforeWrite);
+		for (const piece of rest.toReversed()) nextTr = nextTr.delete(afterWrite.map(piece.from, 1), afterWrite.map(piece.to, -1));
+	}
+	if (commentMark && replacement.length > 0) {
+		const { mapping } = nextTr;
+		const throughEdit = mapping.slice(stepsBefore);
+		let from = throughEdit.map(matchedFrom, -1);
+		let to = throughEdit.map(matchedTo, 1);
+		for (const range of written) {
+			const afterRange = mapping.slice(range.step);
+			from = Math.min(from, afterRange.map(range.from, -1));
+			to = Math.max(to, afterRange.map(range.to, 1));
+		}
+		if (to > from) nextTr = nextTr.addMark(from, to, commentMark);
+	}
+	return nextTr;
+};
+/**
+* Apply a tracked-changes or suggested text replacement as its redline: each
+* change marks exactly the characters it removes as a deletion and writes
+* exactly its new characters as an insertion after them. Characters and
+* inline content outside every change carry no revision, and background
+* clearing records a property change only on the untouched characters of a
+* highlighted stretch a change touches (removed characters keep theirs, and
+* the new text never takes it). `minimal-replacement.ts` states the rest.
+*
+* Returns `null`, before touching the transaction, when the matched span
+* cannot be mapped onto the document character by character; the caller then
+* marks the whole match as replaced, as it always did.
+*/
+const applyMinimalTrackedReplacement = ({ tr, item, replacement, commentMark, replacementBackground, styleResolver, diffText, revisionIdDelete, revisionIdInsert, revisionIdBackgroundSeed, author, date, initials, suggestionId }) => {
+	const schema = tr.doc.type.schema;
+	const insertionType = schema.marks["insertion"];
+	const deletionType = schema.marks["deletion"];
+	if (!insertionType || !deletionType) return null;
+	const plan = planDocumentReplacement({
+		doc: tr.doc,
+		item,
+		replacement,
+		planChanges: (source) => changesFromSegments(diffText(source, replacement))
+	});
+	if (plan === null) return null;
+	let nextTr = tr;
+	let backgroundRevisionIds = [];
+	let nextRevisionId = revisionIdBackgroundSeed;
+	const clearsBackground = replacementBackground === "clear";
+	if (clearsBackground) {
+		const removed = new Set(plan.changes.flatMap((change) => Array.from({ length: change.end - change.start }, (_, offset) => plan.spanStart + change.start + offset)));
+		const kept = [...touchedBackgroundIndices({
+			doc: nextTr.doc,
+			plan
+		})].filter((index) => !removed.has(index));
+		const ranges = unitRanges(new Set(kept), plan.unitAt);
+		if (ranges.length > 0) {
+			const cleared = applyTrackedInlineFormattingToRanges({
+				tr: nextTr,
+				schema,
+				ranges,
+				formatting: REPLACEMENT_BACKGROUND_CLEAR_FORMATTING,
+				revisionIdSeed: revisionIdBackgroundSeed,
+				author,
+				date,
+				initials,
+				suggestionId,
+				...styleResolver !== void 0 ? { styleResolver } : {}
+			});
+			if (cleared.type === "pendingRunPropertyChange") return { type: "pendingRunPropertyChange" };
+			nextTr = cleared.transaction;
+			backgroundRevisionIds = cleared.revisionIds;
+			nextRevisionId = cleared.nextRevisionId;
+		}
+	}
+	const suggestionAttrs = suggestionId === null ? {} : {
+		provenance: "suggested",
+		suggestionId
+	};
+	const revisionAttrs = {
+		author,
+		date,
+		...initials ? { initials } : {},
+		...suggestionAttrs
+	};
+	const deletion = deletionType.create({
+		revisionId: revisionIdDelete,
+		...revisionAttrs
+	});
+	const insertion = insertionType.create({
+		revisionId: revisionIdInsert,
+		...revisionAttrs
+	});
+	const insertedMarks = (marks) => marks.filter((mark) => !REVISION_MARK_NAMES.has(mark.type.name) && mark.type.name !== "runPropertyChange" && !(clearsBackground && BACKGROUND_MARK_NAMES.has(mark.type.name)));
+	for (const change of plan.planned.toReversed()) {
+		const doc = nextTr.doc;
+		let at;
+		let marks;
+		if (change.insertion !== void 0) {
+			at = change.insertion.at;
+			marks = change.insertion.marks(doc);
+		} else {
+			const first = change.pieces.at(0);
+			const last = change.pieces.at(-1);
+			const styleSource = plan.replacementStyleSource(change.change);
+			if (first === void 0 || last === void 0 || styleSource === null) panic("A planned replacement lost the characters it removes");
+			at = last.to;
+			marks = addCarriedMarks(inheritedReplacementMarks(doc, styleSource.from, styleSource.to), surveyReplacedAnnotations(doc, first.from, last.to).carried);
+			for (const piece of change.pieces) {
+				nextTr = nextTr.addMark(piece.from, piece.to, deletion);
+				if (commentMark) nextTr = nextTr.addMark(piece.from, piece.to, commentMark);
+			}
+		}
+		if (change.text.length === 0) continue;
+		const nodes = cleanTextInlineNodes({
+			schema,
+			text: change.text,
+			marks: insertedMarks(marks)
+		});
+		nextTr = nextTr.insert(at, nodes);
+		const end = at + Fragment.fromArray(nodes).size;
+		nextTr = nextTr.addMark(at, end, insertion);
+		if (commentMark) nextTr = nextTr.addMark(at, end, commentMark);
+	}
+	return {
+		type: "applied",
+		transaction: nextTr,
+		backgroundRevisionIds,
+		nextRevisionId
+	};
+};
+/**
+* The clean-text characters of every background stretch a change touches,
+* within the matched span.
+*
+* Text written onto a highlighted value is new text, so the marker saying
+* "fill this in" must not survive on it, and changing one digit of a
+* highlighted amount still fills the whole amount. Background elsewhere in the
+* match is left alone.
+*/
+const touchedBackgroundIndices = ({ doc, plan: { changes, spanStart, spanEnd, unitAt } }) => {
+	const hasBackground = (index) => {
+		const unit = unitAt(index);
+		return (unit === null ? null : doc.nodeAt(unit.from))?.marks.some((mark) => BACKGROUND_MARK_NAMES.has(mark.type.name)) ?? false;
+	};
+	const touched = /* @__PURE__ */ new Set();
+	for (const change of changes) {
+		const start = spanStart + change.start;
+		const end = spanStart + change.end;
+		const touchedFrom = start === end ? Math.max(start - 1, spanStart) : start;
+		const touchedTo = start === end ? Math.min(end + 1, spanEnd) : end;
+		for (let index = touchedFrom; index < touchedTo; index++) {
+			if (touched.has(index) || !hasBackground(index)) continue;
+			touched.add(index);
+			for (let left = index - 1; left >= spanStart && hasBackground(left); left--) touched.add(left);
+			for (let right = index + 1; right < spanEnd && hasBackground(right); right++) touched.add(right);
+		}
+	}
+	return touched;
+};
+/** The document ranges owning clean characters `indices`, merged where they meet. */
+const unitRanges = (indices, unitAt) => {
+	const ranges = [];
+	for (const index of [...indices].toSorted((a, b) => a - b)) {
+		const unit = unitAt(index);
+		if (unit === null) continue;
+		const last = ranges.at(-1);
+		if (last !== void 0 && unit.from <= last.to) last.to = Math.max(last.to, unit.to);
+		else ranges.push({ ...unit });
+	}
+	return ranges;
+};
+/**
+* Clear the highlight and shading of `ranges` (see
+* {@link touchedBackgroundIndices}) before a direct change is written. Only
+* marks change, so no position moves.
+*/
+const clearTouchedBackground = ({ tr, ranges, styleResolver }) => {
+	let nextTr = tr;
+	for (const range of ranges) nextTr = applyInlineFormatting({
+		tr: nextTr,
+		from: range.from,
+		to: range.to,
+		formatting: REPLACEMENT_BACKGROUND_CLEAR_FORMATTING,
+		...styleResolver !== void 0 ? { styleResolver } : {}
+	});
+	return nextTr;
+};
 const resolveStableBlock = ({ snapshot, blockId, liveBlocks, liveBlocksByParaId }) => {
 	const anchor = snapshot.anchors[blockId];
 	if (!anchor) return {