@stll/folio-core 0.49.0 → 0.51.0

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

@@ -35,6 +35,34 @@ type FolioApplyOperationsOptions = {
 };
 /** Options for {@link FolioDocxReviewer.applyDocumentOperations}. */
 type FolioApplyDocumentOperationsOptions = Omit<FolioApplyOperationsOptions, "mode">;
+/**
+ * Why a save rewrote the whole package instead of patching the edited
+ * paragraphs into the original: `structuralChange` (paragraphs added or
+ * removed, or styles, headers, footers or final section properties staged),
+ * `untrackedChange` (an edit the change tracker cannot key to a paragraph), or
+ * `selectiveDeclined` (the patch could not express the edit safely).
+ */
+type FolioReviewerRepackReason = "structuralChange" | "untrackedChange" | "selectiveDeclined";
+/** Options for {@link FolioDocxReviewer.save}. */
+type FolioReviewerSaveOptions = {
+  /**
+   * `"allow"` (default) falls back to a full repack when the selective patch
+   * does not apply; `"refuse"` reports the reason and writes nothing.
+   */
+  repack?: "allow" | "refuse";
+};
+/** Result of {@link FolioDocxReviewer.save}. */
+type FolioReviewerSaveResult = {
+  type: "selective";
+  buffer: ArrayBuffer;
+} | {
+  type: "full-repack";
+  reason: FolioReviewerRepackReason;
+  buffer: ArrayBuffer;
+} | {
+  type: "repackRefused";
+  reason: FolioReviewerRepackReason;
+};
 /** Options for {@link FolioDocxReviewer.getContentAsText}. */
 type FolioGetContentAsTextOptions = {
   /**
@@ -248,6 +276,8 @@ type FolioReviewReplyInput = {
   /** Reply author; defaults to the reviewer's author. */
   author?: string;
   initials?: string;
+  /** ISO-8601 reply date; defaults to the wall clock. */
+  date?: string;
 };
 /** A comment thread discovered in the document. */
 type FolioReviewComment = {
@@ -506,6 +536,12 @@ declare class FolioDocxReviewer {
    * structural edits — the same two-tier path the editor's save uses.
    */
   toBuffer(): Promise<ArrayBuffer>;
+  /**
+   * Serialise like {@link toBuffer} and report which path wrote the package.
+   * With `repack: "refuse"`, a save the selective patch cannot express
+   * returns the reason instead of rewriting every part.
+   */
+  save({ repack: repackPolicy }?: FolioReviewerSaveOptions): Promise<FolioReviewerSaveResult>;
   private assertResolvedStoriesSerialized;
   /**
    * Attempt the selective patch, treating a throw the same as a decline. Odd
@@ -580,4 +616,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, FolioReviewerRepackReason, FolioReviewerSaveOptions, FolioReviewerSaveResult, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };

package/dist/ai-edits/headless.js

@@ -68,16 +68,10 @@ import JSZip from "jszip";
 */
 let commentIdCursor = Date.now();
 let undoHandleCursor = Date.now();
-/**
-* Build the note-free comment thread the apply layer references by id.
-* Mirrors `commentsHelpers.createComment` (a pure object literal there) so a
-* headless `commentOnBlock` / `comment` op serialises the same `comments.xml`
-* shape the editor produces.
-*/
-const createReviewerComment = (id, text, author) => ({
+const createReviewerComment = ({ id, text, author, date }) => ({
 	id,
 	author,
-	date: (/* @__PURE__ */ new Date()).toISOString(),
+	date: date ?? (/* @__PURE__ */ new Date()).toISOString(),
 	content: [{
 		type: "paragraph",
 		formatting: {},
@@ -848,7 +842,12 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			...tableTemplates !== void 0 && { tableTemplates },
 			...replacementBackground !== void 0 && { replacementBackground },
 			createCommentId: (text) => {
-				const comment = createReviewerComment(this.nextCommentId(), text, this.author);
+				const comment = createReviewerComment({
+					id: this.nextCommentId(),
+					text,
+					author: this.author,
+					date: revisionStamp?.date
+				});
 				this.createdComments.push(comment);
 				return comment.id;
 			},
@@ -1080,7 +1079,8 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		const reply = createReply([...this.baseDocument.package.document.comments ?? [], ...this.createdComments], parentId, {
 			author: input.author ?? this.author,
 			text: input.text,
-			...input.initials !== void 0 ? { initials: input.initials } : {}
+			...input.initials !== void 0 ? { initials: input.initials } : {},
+			...input.date !== void 0 && { date: input.date }
 		});
 		if (!reply) return null;
 		this.createdComments.push(reply);
@@ -1344,12 +1344,21 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			structuralChange ||= hasStructuralChanges(entry.state);
 			untrackedChanges ||= hasUntrackedChanges(entry.state);
 		}
+		let path = {
+			type: "selective-first",
+			changedParaIds
+		};
+		if (structuralChange) path = {
+			type: "full-repack",
+			reason: "structuralChange"
+		};
+		else if (untrackedChanges) path = {
+			type: "full-repack",
+			reason: "untrackedChange"
+		};
 		return {
 			document: this.documentFromStateSnapshot(snapshot),
-			path: structuralChange || untrackedChanges ? { type: "full-repack" } : {
-				type: "selective-first",
-				changedParaIds
-			},
+			path,
 			changedNoteParaIds,
 			sectionReferenceRemovals: snapshot.sectionReferenceRemovals,
 			sectionEndpointRemoval: getTrackedSectionEndpointRemoval(snapshot.mainState),
@@ -1363,12 +1372,30 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* structural edits — the same two-tier path the editor's save uses.
 	*/
 	async toBuffer() {
+		const result = await this.save();
+		if (result.type === "repackRefused") return panic("A save that allows a full repack refused to repack", { result });
+		return result.buffer;
+	}
+	/**
+	* Serialise like {@link toBuffer} and report which path wrote the package.
+	* With `repack: "refuse"`, a save the selective patch cannot express
+	* returns the reason instead of rewriting every part.
+	*/
+	async save({ repack: repackPolicy = "allow" } = {}) {
 		const save = this.captureSaveSnapshot();
 		const selective = save.path.type === "selective-first" ? await this.trySelectiveSave(save.document, save.path.changedParaIds) : null;
 		if (selective) {
 			await this.assertResolvedStoriesSerialized(selective, save.resolvedStoryExpectations);
-			return selective;
+			return {
+				type: "selective",
+				buffer: selective
+			};
 		}
+		const reason = save.path.type === "full-repack" ? save.path.reason : "selectiveDeclined";
+		if (repackPolicy === "refuse") return {
+			type: "repackRefused",
+			reason
+		};
 		const repackDocument = {
 			...save.document,
 			originalBuffer: this.originalBuffer
@@ -1385,7 +1412,11 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			repack: repackReferences
 		}) : await repackReferences();
 		await this.assertResolvedStoriesSerialized(buffer, save.resolvedStoryExpectations);
-		return buffer;
+		return {
+			type: "full-repack",
+			reason,
+			buffer
+		};
 	}
 	async assertResolvedStoriesSerialized(buffer, expectations) {
 		if (expectations.length === 0) return;

package/dist/ai-edits/word-diff.js

@@ -836,6 +836,137 @@ const orderDeletionsFirst = (runs) => {
 	flush();
 	return ordered;
 };
+const WORD_CHARACTER = /^[\p{L}\p{N}\p{M}]$/u;
+const LINE_BREAK = /^[\n\r\p{Zl}\p{Zp}]$/u;
+/**
+* How well a change edge between two code points reads, after
+* diff-match-patch's semantic score: the string's edge (an empty side), then
+* a line break, then the gap after a sentence or clause mark, then any space,
+* then any other mark; inside a word is worst.
+*/
+const boundaryScore = (previous, next) => {
+	if (previous.length === 0 || next.length === 0) return 6;
+	if (LINE_BREAK.test(previous) || LINE_BREAK.test(next)) return 4;
+	const previousIsSpace = WHITESPACE.test(previous);
+	const nextIsSpace = WHITESPACE.test(next);
+	if (!previousIsSpace && !WORD_CHARACTER.test(previous) && nextIsSpace) return 3;
+	if (previousIsSpace || nextIsSpace) return 2;
+	return WORD_CHARACTER.test(previous) && WORD_CHARACTER.test(next) ? 0 : 1;
+};
+/** True when `position` falls between the two halves of a surrogate pair. */
+const splitsSurrogatePair = (text, position) => {
+	const low = text.charCodeAt(position);
+	const high = text.charCodeAt(position - 1);
+	return low >= 56320 && low <= 57343 && high >= 55296 && high <= 56319;
+};
+/**
+* Where, among the lossless positions of one change, it reads best. The
+* change may slide by one character whenever the character it gives up
+* equals the one it takes on, which keeps both strings intact. Only the
+* window decides the result, so an insertion and the deletion that undoes it
+* land on the same text; the leftmost of equally good positions wins.
+*/
+const bestSlideStart = (window) => {
+	const { text, start, length, minimumStart, maximumEnd } = window;
+	const scoreAt = (position) => boundaryScore(position === 0 ? window.outsideBefore : codePointBefore(text, position), position === text.length ? window.outsideAfter : codePointAt(text, position));
+	let leftmost = start;
+	while (leftmost > minimumStart && text[leftmost - 1] === text[leftmost + length - 1]) leftmost--;
+	let best = start;
+	let bestScore = -1;
+	for (let candidate = leftmost; candidate + length <= maximumEnd; candidate++) {
+		const end = candidate + length;
+		if (!splitsSurrogatePair(text, candidate) && !splitsSurrogatePair(text, end)) {
+			const startScore = scoreAt(candidate);
+			const endScore = scoreAt(end);
+			if (!(candidate !== start && (startScore === 0 || endScore === 0)) && startScore + endScore > bestScore) {
+				best = candidate;
+				bestScore = startScore + endScore;
+			}
+		}
+		if (end === text.length || text[candidate] !== text[end]) break;
+	}
+	return best;
+};
+/**
+* Whether a change may end up directly beside `neighbour` once the equality
+* between them empties: always beside nothing, an equality or its own kind,
+* and a deletion may precede an insertion; an insertion before a deletion
+* would break deletion-first order.
+*/
+const mayAbut = (first, second) => first === void 0 || second === void 0 || first === "equal" || second === "equal" || first === second || first === "del" && second === "ins";
+/** The code point nearest `index`, walking by `step`, on the side `type` belongs to. */
+const sideCodePoint = (segments, { from, step }, type) => {
+	for (let index = from; index >= 0 && index < segments.length; index += step) {
+		const segment = segments[index];
+		if (segment === void 0 || segment.text.length === 0) continue;
+		if (segment.type === "equal" || segment.type === type) return step === 1 ? codePointAt(segment.text, 0) : codePointBefore(segment.text, segment.text.length);
+	}
+	return "";
+};
+const mergeAdjacentSegments = (segments) => {
+	const merged = [];
+	for (const segment of segments) {
+		const last = merged.at(-1);
+		if (segment.text.length === 0) continue;
+		if (last?.type === segment.type) {
+			last.text += segment.text;
+			continue;
+		}
+		merged.push(segment);
+	}
+	return merged;
+};
+/**
+* Slide every insertion or deletion that sits between equalities to the
+* position that reads best.
+*
+* An LCS places a change arbitrarily among equally long alignments: an
+* appended sentence can be marked as `". New sentence"` before the old
+* sentence's full stop, not `" New sentence."` after it. The redline then
+* marks a stop the author never touched and leaves the new sentence's own
+* unmarked. Sliding moves only where a change's edges fall, so both strings
+* still reconstruct.
+*/
+const slideChangesToReadableBoundaries = (segments) => {
+	const slid = [
+		{
+			type: "equal",
+			text: ""
+		},
+		...segments.map((segment) => ({ ...segment })),
+		{
+			type: "equal",
+			text: ""
+		}
+	];
+	for (let index = 1; index < slid.length - 1; index++) {
+		const change = slid[index];
+		const previous = slid[index - 1];
+		const next = slid[index + 1];
+		if (change === void 0 || previous === void 0 || next === void 0 || change.type === "equal" || previous.type !== "equal" || next.type !== "equal") continue;
+		const text = previous.text + change.text + next.text;
+		const start = bestSlideStart({
+			text,
+			start: previous.text.length,
+			length: change.text.length,
+			minimumStart: mayAbut(slid[index - 2]?.type, change.type) ? 0 : 1,
+			maximumEnd: mayAbut(change.type, slid[index + 2]?.type) ? text.length : text.length - 1,
+			outsideBefore: sideCodePoint(slid, {
+				from: index - 2,
+				step: -1
+			}, change.type),
+			outsideAfter: sideCodePoint(slid, {
+				from: index + 2,
+				step: 1
+			}, change.type)
+		});
+		const end = start + change.text.length;
+		previous.text = text.slice(0, start);
+		change.text = text.slice(start, end);
+		next.text = text.slice(end);
+	}
+	return mergeAdjacentSegments(slid);
+};
 const wholeStringReplacement = (before, after) => {
 	const segments = [];
 	if (before.length > 0) segments.push({
@@ -903,7 +1034,9 @@ const diffWordSegmentsWithBudget = (before, after, options, budget) => {
 		const monotoneRuns = alignMonotoneChange(before, after, beforeTokens, afterTokens, normalization, monotoneDirection);
 		marked = whitespaceIsSignificant ? separateWhitespaceChanges(monotoneRuns) : monotoneRuns;
 	}
-	return toSegments(orderDeletionsFirst(marked));
+	const segments = toSegments(orderDeletionsFirst(marked));
+	const equalRunsAreExact = requestedNormalization.case !== true && requestedNormalization.whitespace !== true;
+	return granularity === "word" && equalRunsAreExact ? slideChangesToReadableBoundaries(segments) : segments;
 };
 /**
 * One internal comparison/apply scope. Every diff shares the same quadratic

package/dist/compare/content-alignment.js

@@ -260,6 +260,44 @@ const pairByUniqueExactText = ({ base, revised, baseFrom, baseTo, revisedFrom, r
 	}
 	return pairs.toReversed();
 };
+/**
+* Unique exact text anchors, then again inside every sub-gap they leave:
+* wording repeated elsewhere in a document is still identity evidence within
+* the one gap where it is unique, so a section's pairing does not depend on
+* whether a neighbouring section happens to repeat it. Each nested pass is
+* charged to the structural allowance; a refused pass leaves its sub-gap to
+* the similarity pairing.
+*/
+const pairByNestedUniqueExactText = ({ workSession, ...gap }) => {
+	const anchors = [];
+	const pending = [gap];
+	for (let current = pending.pop(); current !== void 0; current = pending.pop()) {
+		const found = pairByUniqueExactText(current);
+		if (found.length === 0) continue;
+		anchors.push(...found);
+		let baseFrom = current.baseFrom;
+		let revisedFrom = current.revisedFrom;
+		for (const anchor of [...found, {
+			baseIndex: current.baseTo,
+			revisedIndex: current.revisedTo
+		}]) {
+			const size = anchor.baseIndex - baseFrom + (anchor.revisedIndex - revisedFrom);
+			if (anchor.baseIndex > baseFrom && anchor.revisedIndex > revisedFrom && size <= workSession.remainingStructuralTokenLookups) {
+				workSession.remainingStructuralTokenLookups -= size;
+				pending.push({
+					...current,
+					baseFrom,
+					baseTo: anchor.baseIndex,
+					revisedFrom,
+					revisedTo: anchor.revisedIndex
+				});
+			}
+			baseFrom = anchor.baseIndex + 1;
+			revisedFrom = anchor.revisedIndex + 1;
+		}
+	}
+	return anchors.toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
+};
 const pairsInAnchorGaps = ({ baseLength, revisedLength, anchors, pairGap }) => {
 	const pairs = [];
 	let baseFrom = 0;
@@ -312,9 +350,122 @@ const crossedExactTextBlocks = ({ base, revised, anchors, canPair }) => {
 		revised: crossedRevised
 	};
 };
+/**
+* Minimum multiset Dice similarity for two blocks to pair inside a gap. At
+* 0.5 a paragraph still pairs after gaining up to twice its own length
+* (2n / (n + 3n)); below it, more of the pair would read as changed than
+* kept, which a removal beside an insertion says better.
+*/
+const GAP_PAIR_SIMILARITY_THRESHOLD = .5;
+/**
+* Gap similarities are compared as integers, so a tie is exact rather than an
+* accident of floating-point summation, and a tie-break can sit below the
+* smallest similarity step.
+*/
+const GAP_PAIR_SIMILARITY_SCALE = 1e3;
+/**
+* Words as case-folded runs of letters, marks and digits: punctuation glued to
+* a word ("paragraph." against "paragraph") and a capital at a sentence start
+* would otherwise count a kept word as changed.
+*/
+const gapBlockTokens = (text) => {
+	const counts = /* @__PURE__ */ new Map();
+	let total = 0;
+	for (const match of text.toLowerCase().matchAll(/[\p{L}\p{M}\p{N}]+/gu)) {
+		total += 1;
+		counts.set(match[0], (counts.get(match[0]) ?? 0) + 1);
+	}
+	return {
+		counts,
+		total
+	};
+};
+const gapBlockSimilarity = (base, revised, workSession) => {
+	if (base.total === 0 && revised.total === 0) return {
+		status: "measured",
+		value: 1
+	};
+	if (base.total === 0 || revised.total === 0) return {
+		status: "measured",
+		value: GAP_PAIR_SIMILARITY_THRESHOLD
+	};
+	const [tokens, counterparts] = base.counts.size <= revised.counts.size ? [base.counts, revised.counts] : [revised.counts, base.counts];
+	if (tokens.size > workSession.remainingStructuralTokenLookups) return { status: "budget-exceeded" };
+	workSession.remainingStructuralTokenLookups -= tokens.size;
+	let shared = 0;
+	for (const [token, count] of tokens) shared += Math.min(count, counterparts.get(token) ?? 0);
+	return {
+		status: "measured",
+		value: 2 * shared / (base.total + revised.total)
+	};
+};
+/**
+* The order-preserving pairs of one gap that maximise their summed
+* similarity, each at least `GAP_PAIR_SIMILARITY_THRESHOLD`; offsets are into
+* the gap's slices. Pairing by position instead fuses an inserted block with
+* the neighbour it pushed down, and every block after it with the next one's
+* wording. Null when the work budget refuses the gap.
+*/
+const pairGapBySimilarity = ({ base, revised, canPair, workSession }) => {
+	const baseCount = base.length;
+	const revisedCount = revised.length;
+	if (!claimFolioContentAlignmentCells(baseCount, revisedCount, workSession)) return null;
+	const revisedTokens = revised.map((block) => gapBlockTokens(block.block.text));
+	const similarityStep = Math.min(baseCount, revisedCount) + 1;
+	const similarity = new Float64Array(baseCount * revisedCount).fill(-1);
+	const candidateBase = /* @__PURE__ */ new Set();
+	const candidateRevised = /* @__PURE__ */ new Set();
+	for (const [baseOffset, baseBlock] of base.entries()) {
+		const baseTokens = gapBlockTokens(baseBlock.block.text);
+		for (const [revisedOffset, revisedBlock] of revised.entries()) {
+			if (!canPair(baseBlock, revisedBlock)) continue;
+			const tokens = revisedTokens[revisedOffset] ?? panic("A gap block has no token profile");
+			const measured = baseBlock.block.text === revisedBlock.block.text ? {
+				status: "measured",
+				value: 1
+			} : gapBlockSimilarity(baseTokens, tokens, workSession);
+			if (measured.status === "budget-exceeded") return null;
+			if (measured.value >= GAP_PAIR_SIMILARITY_THRESHOLD) {
+				const sameLabel = baseBlock.block.displayLabel !== void 0 && baseBlock.block.displayLabel === revisedBlock.block.displayLabel;
+				similarity[baseOffset * revisedCount + revisedOffset] = Math.round(measured.value * GAP_PAIR_SIMILARITY_SCALE) * similarityStep + (sameLabel ? 1 : 0);
+				candidateBase.add(baseOffset);
+				candidateRevised.add(revisedOffset);
+			}
+		}
+	}
+	const width = revisedCount + 1;
+	const scores = new Float64Array((baseCount + 1) * width);
+	const cellSimilarity = (baseOffset, revisedOffset) => similarity[baseOffset * revisedCount + revisedOffset] ?? -1;
+	const score = (row, column) => scores[row * width + column] ?? 0;
+	for (let row = baseCount - 1; row >= 0; row--) for (let column = revisedCount - 1; column >= 0; column--) {
+		const cell = cellSimilarity(row, column);
+		scores[row * width + column] = Math.max(score(row + 1, column), score(row, column + 1), cell < 0 ? 0 : score(row + 1, column + 1) + cell);
+	}
+	const pairs = [];
+	let row = 0;
+	let column = 0;
+	while (row < baseCount && column < revisedCount) {
+		const cell = cellSimilarity(row, column);
+		if (cell >= 0 && score(row, column) === score(row + 1, column + 1) + cell) {
+			pairs.push({
+				baseIndex: row,
+				revisedIndex: column
+			});
+			row += 1;
+			column += 1;
+		} else if (score(row, column) === score(row + 1, column)) row += 1;
+		else column += 1;
+	}
+	return {
+		pairs,
+		candidateBase,
+		candidateRevised
+	};
+};
 const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 	const stableIdMismatch = options.stableIdMismatch ?? "separate";
 	const idStability = options.idStability ?? folioContentIdStability;
+	const workSession = options.workSession ?? createFolioContentAlignmentWorkSession();
 	const prepared = prepareAlignmentBlocks({
 		baseBlocks,
 		revisedBlocks,
@@ -335,14 +486,15 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		baseLength: prepared.base.length,
 		revisedLength: prepared.revised.length,
 		anchors: stableIdAnchors,
-		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByUniqueExactText({
+		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByNestedUniqueExactText({
 			base: prepared.base,
 			revised: prepared.revised,
 			baseFrom,
 			baseTo,
 			revisedFrom,
 			revisedTo,
-			canPair
+			canPair,
+			workSession
 		})
 	});
 	const exactAndStableAnchors = [...stableIdAnchors, ...exactTextAnchors].toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
@@ -368,12 +520,13 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		canPair
 	});
 	const events = [];
+	const fusesACrossing = (baseBlock, revisedBlock) => baseBlock.block.text !== revisedBlock.block.text && crossed.base.has(baseBlock.index) && crossed.revised.has(revisedBlock.index);
 	const emitPositionalGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
 		const pairedCount = Math.min(baseTo - baseFrom, revisedTo - revisedFrom);
 		for (let offset = 0; offset < pairedCount; offset++) {
 			const baseBlock = prepared.base[baseFrom + offset];
 			const revisedBlock = prepared.revised[revisedFrom + offset];
-			if (baseBlock && revisedBlock) if (baseBlock.block.text !== revisedBlock.block.text && crossed.base.has(baseBlock.index) && crossed.revised.has(revisedBlock.index) || !canPair(baseBlock, revisedBlock)) {
+			if (baseBlock && revisedBlock) if (fusesACrossing(baseBlock, revisedBlock) || !canPair(baseBlock, revisedBlock)) {
 				events.push({
 					type: "baseOnly",
 					block: baseBlock.block
@@ -403,10 +556,72 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 			});
 		}
 	};
+	/**
+	* A gap's blocks pair by similarity, whether or not its sides are equal in
+	* length: an equal gap can hide an insertion beside a deletion, and pairing
+	* it by position reads each kept block as a rewrite of its neighbour. The
+	* similar pairs anchor the rest; blocks between two anchors pair by position
+	* only when neither side offered any candidate and the counts match, which
+	* reads a block rewritten beyond recognition as the modification it is.
+	*/
+	const emitGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
+		const pairing = pairGapBySimilarity({
+			base: prepared.base.slice(baseFrom, baseTo),
+			revised: prepared.revised.slice(revisedFrom, revisedTo),
+			canPair: (baseBlock, revisedBlock) => !fusesACrossing(baseBlock, revisedBlock) && canPair(baseBlock, revisedBlock),
+			workSession
+		});
+		if (pairing === null) {
+			emitPositionalGap(baseFrom, baseTo, revisedFrom, revisedTo);
+			return;
+		}
+		const { pairs, candidateBase, candidateRevised } = pairing;
+		let baseCursor = baseFrom;
+		let revisedCursor = revisedFrom;
+		const hasCandidate = (candidates, from, to) => {
+			for (let offset = from; offset < to; offset++) if (candidates.has(offset)) return true;
+			return false;
+		};
+		const emitUnpairedUntil = (baseEnd, revisedEnd) => {
+			if (baseEnd - baseCursor === revisedEnd - revisedCursor && !hasCandidate(candidateBase, baseCursor - baseFrom, baseEnd - baseFrom) && !hasCandidate(candidateRevised, revisedCursor - revisedFrom, revisedEnd - revisedFrom)) {
+				emitPositionalGap(baseCursor, baseEnd, revisedCursor, revisedEnd);
+				baseCursor = baseEnd;
+				revisedCursor = revisedEnd;
+				return;
+			}
+			for (; baseCursor < baseEnd; baseCursor++) {
+				const block = prepared.base[baseCursor]?.block;
+				if (block) events.push({
+					type: "baseOnly",
+					block
+				});
+			}
+			for (; revisedCursor < revisedEnd; revisedCursor++) {
+				const block = prepared.revised[revisedCursor]?.block;
+				if (block) events.push({
+					type: "revisedOnly",
+					block
+				});
+			}
+		};
+		for (const pair of pairs) {
+			emitUnpairedUntil(baseFrom + pair.baseIndex, revisedFrom + pair.revisedIndex);
+			const baseBlock = prepared.base[baseCursor]?.block;
+			const revisedBlock = prepared.revised[revisedCursor]?.block;
+			if (baseBlock && revisedBlock) events.push({
+				type: "pair",
+				baseBlock,
+				revisedBlock
+			});
+			baseCursor += 1;
+			revisedCursor += 1;
+		}
+		emitUnpairedUntil(baseTo, revisedTo);
+	};
 	let baseCursor = 0;
 	let revisedCursor = 0;
 	for (const anchor of anchors) {
-		emitPositionalGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
+		emitGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
 		const baseBlock = prepared.base[anchor.baseIndex]?.block;
 		const revisedBlock = prepared.revised[anchor.revisedIndex]?.block;
 		if (baseBlock && revisedBlock) events.push({
@@ -417,7 +632,7 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		baseCursor = anchor.baseIndex + 1;
 		revisedCursor = anchor.revisedIndex + 1;
 	}
-	emitPositionalGap(baseCursor, prepared.base.length, revisedCursor, prepared.revised.length);
+	emitGap(baseCursor, prepared.base.length, revisedCursor, prepared.revised.length);
 	return events;
 };
 const alignFolioContentBlocks = (baseBlocks, revisedBlocks, options = {}) => alignFolioContentBlocksInScope(baseBlocks, revisedBlocks, {

package/dist/compare/content.d.ts

@@ -186,6 +186,7 @@ type ParagraphMarkPlan<Block extends FolioContentBlock> = {
   revisedBlock: Block;
   separator: string;
 };
+/** Plans keyed by their first step; each consumes the step after it. */
 declare const detectFolioContentParagraphMarkPlans: <Block extends FolioContentBlock>(steps: readonly FolioContentAlignmentStep<Block>[]) => ReadonlyMap<number, ParagraphMarkPlan<Block>>;
 type MovePair<Block extends FolioContentBlock> = {
   baseBlock: Block;