@stll/folio-core 0.52.0 → 0.53.0

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

@@ -5,9 +5,10 @@ import { FolioAIEditApplyOutcome, FolioAIEditView, FolioRevisionStamp, FolioWord
 import { DocPositionRange, clampRangeToDocSize, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange } from "./blockRange.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
 import { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
+import { FOLIO_PENDING_SUGGESTION_VERSION, FolioPendingSuggestionLoadResult, FolioPendingSuggestionRecord, FolioPendingSuggestionRegistry, FolioPendingSuggestionStaleReason, createPendingSuggestionSourceSnapshot } from "./pending-suggestions.js";
 import { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
 import { createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./snapshot.js";
 import { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsToStoryOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioEditableDocumentStoryHandle, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, isFolioResolvedReviewedView, isFolioReviewedView } from "./headless.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./scoped-reading.js";
 import { getFolioParaIdFromBlockId } from "../types/block-id.js";
-export { type ApplyFolioDocumentOperationsOptions, type DocPositionRange, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIEditView, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIInsertFormattingScope, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsToStoryOptions, type FolioCommentAnchor, type FolioContentParagraphKind, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, type FolioEditableDocumentStoryHandle, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeKind, type FolioReviewedStory, type FolioReviewedView, type FolioRevisionStamp, type FolioWordDiffOptions, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioAIContentBlock, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange };
+export { type ApplyFolioDocumentOperationsOptions, type DocPositionRange, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_PENDING_SUGGESTION_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIEditView, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIInsertFormattingScope, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsToStoryOptions, type FolioCommentAnchor, type FolioContentParagraphKind, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, type FolioEditableDocumentStoryHandle, type FolioPendingSuggestionLoadResult, type FolioPendingSuggestionRecord, FolioPendingSuggestionRegistry, type FolioPendingSuggestionStaleReason, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeKind, type FolioReviewedStory, type FolioReviewedView, type FolioRevisionStamp, type FolioWordDiffOptions, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, createPendingSuggestionSourceSnapshot, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioAIContentBlock, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange };

package/dist/ai-edits/index.js

@@ -4,8 +4,9 @@ import { applyFolioAIEditOperations } from "./apply.js";
 import { clampRangeToDocSize, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange } from "./blockRange.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
 import { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, UnsupportedFolioReviewedViewError, isFolioResolvedReviewedView, isFolioReviewedView } from "./headless.js";
+import { FOLIO_PENDING_SUGGESTION_VERSION, FolioPendingSuggestionRegistry, createPendingSuggestionSourceSnapshot } from "./pending-suggestions.js";
 import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./scoped-reading.js";
 import { createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./snapshot.js";
 import { WORD_DIFF_GRANULARITIES, diffWordSegments } from "./word-diff.js";
-export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, WORD_DIFF_GRANULARITIES, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioAIContentBlock, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange };
+export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_PENDING_SUGGESTION_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, FolioPendingSuggestionRegistry, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, WORD_DIFF_GRANULARITIES, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, createPendingSuggestionSourceSnapshot, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioAIContentBlock, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange, resolvePassageRange };

package/dist/ai-edits/minimal-replacement.d.ts

@@ -36,11 +36,13 @@ declare const shortestTokenDiff: (before: readonly string[], after: readonly str
  *
  * Words (with their leading whitespace, and edge punctuation on its own; see
  * `tokenizeWords`) are aligned by the shortest edit script, and each changed
- * stretch is then trimmed to the characters that actually differ, so
- * appending a letter to a word that spans two runs leaves both runs alone. A
- * rewrite past {@link MAX_TOKEN_EDITS}, or a diff that does not reconstruct
- * both strings exactly (it never should), is one change over the whole span,
- * trimmed the same way.
+ * stretch is then trimmed: to whole words it shares at either end, and once
+ * what is left lies within one word on both sides, to the letters that
+ * actually differ. Appending a letter to a word that spans two runs leaves
+ * both runs alone, and a rewrite of several words never keeps a letter two of
+ * them merely happen to share. A rewrite past {@link MAX_TOKEN_EDITS}, or a
+ * diff that does not reconstruct both strings exactly (it never should), is
+ * one change over the whole span, trimmed the same way.
  */
 declare const planTextChanges: (source: string, replacement: string) => TextChange[];
 /**
@@ -58,7 +60,20 @@ declare const changesFromSegments: (segments: readonly WordDiffSegment[]) => Tex
  * `spans` are in the same coordinates as the changes (the source span's).
  */
 declare const widenChangesToAtomicSpans: (source: string, changes: readonly TextChange[], spans: readonly AtomicTextSpan[]) => TextChange[];
+/**
+ * `changes` cut around every atomic span (a field result) that `kept`, another
+ * plan of the same replacement, leaves untouched.
+ *
+ * A redline's changes are cut for a reader and may swallow a field whose
+ * displayed text the replacement repeats; rewriting it deletes the field and
+ * inserts its text as plain text, which the direct edit, keeping the field,
+ * never does. Cutting the change around the field keeps it in both modes,
+ * and a piece of the cut that no longer changes anything is dropped. Where
+ * the field's text does not stand in the change's new text exactly where
+ * `kept` puts it, the change is left whole.
+ */
+declare const keepAtomicSpans: (source: string, replacement: string, changes: readonly TextChange[], kept: readonly TextChange[], spans: readonly AtomicTextSpan[]) => TextChange[];
 /** `source` with `changes` applied; the invariant the planner owes. */
 declare const applyTextChanges: (source: string, changes: readonly TextChange[]) => string;
 //#endregion
-export { AtomicTextSpan, MAX_TOKEN_EDITS, TextChange, applyTextChanges, changesFromSegments, commonPrefixLength, commonSuffixLength, planTextChanges, shortestTokenDiff, widenChangesToAtomicSpans };
+export { AtomicTextSpan, MAX_TOKEN_EDITS, TextChange, applyTextChanges, changesFromSegments, commonPrefixLength, commonSuffixLength, keepAtomicSpans, planTextChanges, shortestTokenDiff, widenChangesToAtomicSpans };

package/dist/ai-edits/minimal-replacement.js

@@ -36,14 +36,24 @@ import { tokenizeWords } from "./word-diff.js";
 * A replacement carrying inline emphasis markup (`**bold**`) states its own
 * formatting and still replaces the match whole in direct mode.
 *
+* A change across several words is trimmed only to whole words it shares
+* with the replacement at either end ({@link planTextChanges}): the letters
+* two different words happen to share are not the same text, and keeping one
+* would leave part of a new word in the formatting of the word it replaced.
+*
 * Tracked-changes and suggested modes cut their changes from the redline diff
 * instead ({@link changesFromSegments}: word or character granularity, as the
 * caller asked), and map them onto the document by the same rules. A change
 * marks exactly the characters it removes as a deletion, which keeps their
-* runs, and writes its text as an insertion after them, formatted as the
-* first removed character that is not a note reference; a pure insertion is
-* placed and formatted as above. Nothing outside a change is wrapped in a
-* revision.
+* runs, and writes its text as an insertion after them. The insertion's
+* formatting is not decided by the redline's cut: every character of it takes
+* the formatting the direct edit gives that character, so accepting the
+* redline leaves exactly what the direct edit writes, although the redline
+* rewrites whole words the direct edit only touches. Nothing outside a change
+* is wrapped in a revision.
+*
+* Whichever mode applies it, a replacement that rewrites characters of more
+* than one formatting reports `uniformReplacementFormatting` in its receipt.
 *
 * This module is the pure half: clean-text offsets in, changes out. The
 * applier maps each change onto the document.
@@ -64,15 +74,64 @@ const commonSuffixLength = (a, b) => {
 	while (length < limit && a.charCodeAt(a.length - 1 - length) === b.charCodeAt(b.length - 1 - length)) length++;
 	return length > 0 && isLowSurrogate(a.charCodeAt(a.length - length)) ? length - 1 : length;
 };
-/** `change` without the characters its deleted and inserted text share at either end. */
+/** A letter, digit, combining mark or connector: what a word is made of. */
+const WORD_CHARACTER = /^[\p{L}\p{N}\p{M}\p{Pc}]$/u;
+const codePointBefore = (text, index) => {
+	const low = text.charCodeAt(index - 1);
+	return index >= 2 && isLowSurrogate(low) && isHighSurrogate(text.charCodeAt(index - 2)) ? text.slice(index - 2, index) : text.slice(index - 1, index);
+};
+const codePointAt = (text, index) => String.fromCodePoint(text.codePointAt(index) ?? 0);
+/** Whether `index` separates two words of `text` rather than two letters of one. */
+const isWordBoundary = (text, index) => index <= 0 || index >= text.length || !WORD_CHARACTER.test(codePointBefore(text, index)) || !WORD_CHARACTER.test(codePointAt(text, index));
+/** At most one word, with whatever separators around it. */
+const SINGLE_WORD = /^[^\p{L}\p{N}\p{M}\p{Pc}]*[\p{L}\p{N}\p{M}\p{Pc}]*[^\p{L}\p{N}\p{M}\p{Pc}]*$/u;
+/**
+* The longest length up to `length` that ends (`fromEnd` false) or starts
+* (`fromEnd` true) on a word boundary of both strings.
+*/
+const wordAlignedLength = (left, right, length, fromEnd) => {
+	for (let candidate = length; candidate > 0; candidate--) {
+		const leftIndex = fromEnd ? left.length - candidate : candidate;
+		const rightIndex = fromEnd ? right.length - candidate : candidate;
+		if (isWordBoundary(left, leftIndex) && isWordBoundary(right, rightIndex)) return candidate;
+	}
+	return 0;
+};
+/**
+* `change` without the characters its deleted and inserted text share at either
+* end.
+*
+* Within one word, letter by letter: `Supplier` to `Suppliers` inserts one `s`
+* and leaves both runs of a word split across two alone. A change spanning
+* several words keeps only whole words it shares at an end: the `s` that
+* `agrees` and `performs` happen to end with is a coincidence, and keeping it
+* would leave the last letter of `performs` in the formatting `agrees` had
+* while the rest of the word takes the formatting of the text it replaces.
+*/
 const trimChange = (source, change) => {
-	const removed = source.slice(change.start, change.end);
-	const prefix = commonPrefixLength(removed, change.text);
-	const suffix = commonSuffixLength(removed.slice(prefix), change.text.slice(prefix));
+	let removed = source.slice(change.start, change.end);
+	let inserted = change.text;
+	let prefix = 0;
+	let suffix = 0;
+	for (const granularity of ["word", "letter"]) {
+		const withinOneWord = SINGLE_WORD.test(removed) && SINGLE_WORD.test(inserted);
+		if (granularity === "letter" && !withinOneWord) break;
+		const sharedPrefix = commonPrefixLength(removed, inserted);
+		const nextPrefix = withinOneWord ? sharedPrefix : wordAlignedLength(removed, inserted, sharedPrefix, false);
+		removed = removed.slice(nextPrefix);
+		inserted = inserted.slice(nextPrefix);
+		const sharedSuffix = commonSuffixLength(removed, inserted);
+		const nextSuffix = withinOneWord ? sharedSuffix : wordAlignedLength(removed, inserted, sharedSuffix, true);
+		removed = removed.slice(0, removed.length - nextSuffix);
+		inserted = inserted.slice(0, inserted.length - nextSuffix);
+		prefix += nextPrefix;
+		suffix += nextSuffix;
+		if (withinOneWord) break;
+	}
 	const trimmed = {
 		start: change.start + prefix,
 		end: change.end - suffix,
-		text: change.text.slice(prefix, change.text.length - suffix)
+		text: inserted
 	};
 	return trimmed.start === trimmed.end && trimmed.text.length === 0 ? null : trimmed;
 };
@@ -169,11 +228,13 @@ const shortestTokenDiff = (before, after, maxEdits = MAX_TOKEN_EDITS) => {
 *
 * Words (with their leading whitespace, and edge punctuation on its own; see
 * `tokenizeWords`) are aligned by the shortest edit script, and each changed
-* stretch is then trimmed to the characters that actually differ, so
-* appending a letter to a word that spans two runs leaves both runs alone. A
-* rewrite past {@link MAX_TOKEN_EDITS}, or a diff that does not reconstruct
-* both strings exactly (it never should), is one change over the whole span,
-* trimmed the same way.
+* stretch is then trimmed: to whole words it shares at either end, and once
+* what is left lies within one word on both sides, to the letters that
+* actually differ. Appending a letter to a word that spans two runs leaves
+* both runs alone, and a rewrite of several words never keeps a letter two of
+* them merely happen to share. A rewrite past {@link MAX_TOKEN_EDITS}, or a
+* diff that does not reconstruct both strings exactly (it never should), is
+* one change over the whole span, trimmed the same way.
 */
 const planTextChanges = (source, replacement) => {
 	if (source === replacement) return [];
@@ -268,6 +329,64 @@ const widenChangesToAtomicSpans = (source, changes, spans) => {
 	}
 	return merged;
 };
+/** Where each character `changes` keeps of `source` lands in the result. */
+const keptPositions = (source, changes) => {
+	const kept = /* @__PURE__ */ new Map();
+	let shift = 0;
+	let cursor = 0;
+	for (const change of changes) {
+		for (; cursor < change.start; cursor++) kept.set(cursor, cursor + shift);
+		cursor = change.end;
+		shift += change.text.length - (change.end - change.start);
+	}
+	for (; cursor < source.length; cursor++) kept.set(cursor, cursor + shift);
+	return kept;
+};
+/**
+* `changes` cut around every atomic span (a field result) that `kept`, another
+* plan of the same replacement, leaves untouched.
+*
+* A redline's changes are cut for a reader and may swallow a field whose
+* displayed text the replacement repeats; rewriting it deletes the field and
+* inserts its text as plain text, which the direct edit, keeping the field,
+* never does. Cutting the change around the field keeps it in both modes,
+* and a piece of the cut that no longer changes anything is dropped. Where
+* the field's text does not stand in the change's new text exactly where
+* `kept` puts it, the change is left whole.
+*/
+const keepAtomicSpans = (source, replacement, changes, kept, spans) => {
+	if (spans.length === 0) return [...changes];
+	const keptAt = keptPositions(source, kept);
+	const cut = [];
+	let shift = 0;
+	for (const change of changes) {
+		const replacementStart = change.start + shift;
+		shift += change.text.length - (change.end - change.start);
+		let sourceCursor = change.start;
+		let textCursor = 0;
+		for (const { offset, length } of spans) {
+			if (offset < sourceCursor || offset + length > change.end || length === 0) continue;
+			const lands = keptAt.get(offset);
+			const wholeAndInOrder = lands !== void 0 && Array.from({ length }, (_, index) => keptAt.get(offset + index)).every((position, index) => position === lands + index);
+			const local = lands === void 0 ? -1 : lands - replacementStart;
+			if (!wholeAndInOrder || local < textCursor || change.text.slice(local, local + length) !== source.slice(offset, offset + length)) continue;
+			cut.push({
+				start: sourceCursor,
+				end: offset,
+				text: change.text.slice(textCursor, local)
+			});
+			sourceCursor = offset + length;
+			textCursor = local + length;
+		}
+		cut.push({
+			start: sourceCursor,
+			end: change.end,
+			text: change.text.slice(textCursor)
+		});
+	}
+	const pieces = cut.filter(({ start, end, text }) => (start < end || text.length > 0) && source.slice(start, end) !== text);
+	return applyTextChanges(source, pieces) === replacement ? pieces : [...changes];
+};
 /** `source` with `changes` applied; the invariant the planner owes. */
 const applyTextChanges = (source, changes) => {
 	let result = "";
@@ -279,4 +398,4 @@ const applyTextChanges = (source, changes) => {
 	return result + source.slice(cursor);
 };
 //#endregion
-export { MAX_TOKEN_EDITS, applyTextChanges, changesFromSegments, commonPrefixLength, commonSuffixLength, planTextChanges, shortestTokenDiff, widenChangesToAtomicSpans };
+export { MAX_TOKEN_EDITS, applyTextChanges, changesFromSegments, commonPrefixLength, commonSuffixLength, keepAtomicSpans, planTextChanges, shortestTokenDiff, widenChangesToAtomicSpans };

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

@@ -0,0 +1,23 @@
+import { FolioAIEditOperation, FolioAIListNumbering, FolioAIListReference, FolioAINewListReference } from "./types.js";
+import { NumberingMap } from "../docx/numberingParser.js";
+//#region src/ai-edits/newListNumbering.d.ts
+/** Whether `numbering` asks for a new list rather than naming an instance. */
+declare const isFolioAINewListReference: (numbering: FolioAIListNumbering) => numbering is FolioAINewListReference;
+/**
+ * The concrete instance an operation's numbering names once new lists are
+ * resolved. A new-list request reaching this point skipped resolution, which
+ * is a bug in the apply path rather than a malformed operation.
+ */
+declare const concreteListReference: (numbering: FolioAIListNumbering) => FolioAIListReference;
+type ResolvedNewLists = {
+  operations: FolioAIEditOperation[];
+  numbering: NumberingMap | null;
+};
+/**
+ * Replace every new-list request with a reference to an instance minted for
+ * its operation: one instance per operation and kind. `numbering` is the map
+ * the batch applies against; the result's map adds the minted instances.
+ */
+declare const resolveNewListOperations: (operations: readonly FolioAIEditOperation[], numbering: NumberingMap | null) => ResolvedNewLists;
+//#endregion
+export { concreteListReference, isFolioAINewListReference, resolveNewListOperations };

package/dist/ai-edits/newListNumbering.js

@@ -0,0 +1,94 @@
+import { mintListInstance } from "../docx/listNumberingInstances.js";
+import { createNumberingMap } from "../docx/numberingParser.js";
+import { panic } from "better-result";
+//#region src/ai-edits/newListNumbering.ts
+/**
+* Operations that start a new list (`numbering: { start: "new", kind }`)
+* resolved to the numbering instance each one defines.
+*
+* The instance is minted against the document's numbering (the package's
+* definitions plus every instance its paragraphs already define), so its id
+* collides with nothing, and against the instances earlier operations in the
+* batch minted, so two operations start two lists. The paragraphs the
+* operation numbers then carry the instance's rendering, which is what
+* defines it in the saved package (see `docx/listNumberingInstances.ts`).
+*/
+/** Whether `numbering` asks for a new list rather than naming an instance. */
+const isFolioAINewListReference = (numbering) => "start" in numbering;
+/**
+* The concrete instance an operation's numbering names once new lists are
+* resolved. A new-list request reaching this point skipped resolution, which
+* is a bug in the apply path rather than a malformed operation.
+*/
+const concreteListReference = (numbering) => {
+	if (isFolioAINewListReference(numbering)) return panic("A new-list numbering request reached apply unresolved");
+	return numbering;
+};
+/**
+* Replace every new-list request with a reference to an instance minted for
+* its operation: one instance per operation and kind. `numbering` is the map
+* the batch applies against; the result's map adds the minted instances.
+*/
+const resolveNewListOperations = (operations, numbering) => {
+	let definitions = numbering?.definitions;
+	let minted = false;
+	const resolveOperation = (operation) => {
+		const instances = /* @__PURE__ */ new Map();
+		const resolve = (value) => {
+			if (value === null || value === void 0 || !isFolioAINewListReference(value)) return value;
+			let numId = instances.get(value.kind);
+			if (numId === void 0) {
+				const instance = mintListInstance(definitions, { kind: value.kind });
+				definitions = instance.definitions;
+				numId = instance.numId;
+				instances.set(value.kind, numId);
+				minted = true;
+			}
+			return {
+				numId,
+				level: value.level ?? 0
+			};
+		};
+		const resolveProperties = (properties) => properties?.numbering ? {
+			...properties,
+			numbering: resolve(properties.numbering)
+		} : properties;
+		switch (operation.type) {
+			case "insertAfterBlock":
+			case "insertBeforeBlock": return operation.numbering ? {
+				...operation,
+				numbering: resolve(operation.numbering)
+			} : operation;
+			case "setBlockParagraphProperties": return operation.properties.numbering ? {
+				...operation,
+				properties: {
+					...operation.properties,
+					numbering: resolve(operation.properties.numbering)
+				}
+			} : operation;
+			case "splitBlock": {
+				const firstParagraphProperties = resolveProperties(operation.firstParagraphProperties);
+				const secondParagraphProperties = resolveProperties(operation.secondParagraphProperties);
+				return {
+					...operation,
+					...firstParagraphProperties && { firstParagraphProperties },
+					...secondParagraphProperties && { secondParagraphProperties }
+				};
+			}
+			case "mergeBlockWithNext": {
+				const mergedParagraphProperties = resolveProperties(operation.mergedParagraphProperties);
+				return {
+					...operation,
+					...mergedParagraphProperties && { mergedParagraphProperties }
+				};
+			}
+			default: return operation;
+		}
+	};
+	return {
+		operations: operations.map(resolveOperation),
+		numbering: minted && definitions ? createNumberingMap(definitions) : numbering
+	};
+};
+//#endregion
+export { concreteListReference, isFolioAINewListReference, resolveNewListOperations };

package/dist/ai-edits/note-references.d.ts

@@ -0,0 +1,96 @@
+import { NoteReferenceKind } from "../utils/noteReferenceLabels.js";
+import { TextChange } from "./minimal-replacement.js";
+import { CleanBlockText } from "./clean-text.js";
+import { Node } from "prosemirror-model";
+//#region src/ai-edits/note-references.d.ts
+/** Which note a reference names: its kind and its package id. */
+type NoteReferenceIdentity = {
+  noteType: NoteReferenceKind;
+  noteId: string;
+};
+/** The reference a text node carries, or `null` for ordinary text. */
+declare const noteReferenceOf: (node: Node) => NoteReferenceIdentity | null;
+/**
+ * The marker each reference of a story shows, keyed by note: numbered once
+ * for a whole story so every block reads the same number the Markdown export
+ * gives it, and so an edit elsewhere in one batch cannot renumber a block the
+ * batch resolved earlier.
+ */
+type NoteReferenceLabels = {
+  labelOf: (reference: NoteReferenceIdentity) => string | undefined;
+};
+/** Labels that grow as the blocks of a story are numbered, in reading order. */
+type NoteReferenceLabeler = NoteReferenceLabels & {
+  /**
+   * Number the references of one block. A reference the clean view omits
+   * (tracked-deleted, hidden) takes no number, exactly as its characters take
+   * no place in the clean text.
+   */
+  numberBlock: (block: Node) => void;
+};
+/**
+ * The one numbering every AI reader of a story shares. The snapshot numbers
+ * block by block inside its own walk; `collectNoteReferenceLabels` (with the
+ * snapshot, so both skip what the snapshot skips) numbers a whole story.
+ */
+declare const createNoteReferenceLabeler: () => NoteReferenceLabeler;
+/**
+ * The text a reader shows for an inline text node: a note reference's marker
+ * instead of its package id. A reference the clean view omits (a tracked
+ * deletion) has no number there, and reads as an unnumbered marker.
+ */
+declare const readerTextOf: (node: Node, labels: NoteReferenceLabels) => string;
+/** A note reference's marker inside a span of clean text, relative to the span. */
+type NoteReferenceSpan = {
+  offset: number;
+  length: number;
+};
+type StructuralBoundaries = Pick<CleanBlockText, "structuralBoundaries">;
+/** The markers lying wholly inside clean text `[start, end)`, relative to `start`. */
+declare const noteReferenceSpansWithin: ({ structuralBoundaries }: StructuralBoundaries, start: number, end: number) => NoteReferenceSpan[];
+/** Whether clean text `[start, end)` starts or ends inside a reference's marker. */
+declare const cutsIntoNoteReference: ({ structuralBoundaries }: StructuralBoundaries, start: number, end: number) => boolean;
+/**
+ * @internal Run `apply` with its text operations free to remove note
+ * references and to write marker text in place of new ones.
+ *
+ * Only a document comparison does this. Its operations come from a revised
+ * document that adds and removes references, so refusing them would drop the
+ * edit; each marker it writes is turned back into the reference the revised
+ * document holds once the operations land (`compare/inline-atoms.ts`), and a
+ * removed reference is a tracked deletion of the reference itself. Every other
+ * caller keeps the protection. The scope is synchronous, like the applier.
+ */
+declare const withComparisonNoteReferenceEdits: <T>(apply: () => T) => T;
+/** @internal Whether the running apply belongs to a comparison (see above). */
+declare const noteReferenceEditsAllowed: () => boolean;
+/** The pieces of a replacement between the markers it has to keep. */
+type NoteReferenceSegments = {
+  /** The source text between markers, with its offset in the source. */
+  source: {
+    offset: number;
+    text: string;
+  }[];
+  /** What each source piece becomes. */
+  replacement: string[];
+};
+/**
+ * Pair a text replacement with the reference markers its source holds.
+ *
+ * A reference is not text, so a replacement may only rewrite the prose around
+ * it: every marker of `source` has to reappear in `replacement`, in order, and
+ * the prose between two markers becomes the prose between the same two. A
+ * replacement that drops, reorders or rewrites a marker — or writes a new
+ * marker-shaped string, which would read as a reference and be none — answers
+ * `null`: the edit is refused rather than deleting a reference, or leaving
+ * text behind that claims to be one.
+ */
+declare const segmentsAroundNoteReferences: (source: string, replacement: string, spans: readonly NoteReferenceSpan[]) => NoteReferenceSegments | null;
+/**
+ * Plan a replacement's changes piece by piece between the markers it keeps, so
+ * no change ever touches a reference. `null` when the replacement does not
+ * keep them (see {@link segmentsAroundNoteReferences}).
+ */
+declare const planChangesAroundNoteReferences: (source: string, replacement: string, spans: readonly NoteReferenceSpan[], planChanges: (source: string, replacement: string) => readonly TextChange[]) => TextChange[] | null;
+//#endregion
+export { NoteReferenceIdentity, NoteReferenceLabeler, NoteReferenceLabels, NoteReferenceSpan, createNoteReferenceLabeler, cutsIntoNoteReference, noteReferenceEditsAllowed, noteReferenceOf, noteReferenceSpansWithin, planChangesAroundNoteReferences, readerTextOf, segmentsAroundNoteReferences, withComparisonNoteReferenceEdits };

package/dist/ai-edits/note-references.js

@@ -0,0 +1,139 @@
+import { createNoteReferenceNumbering, noteReferenceMarker } from "../utils/noteReferenceLabels.js";
+//#region src/ai-edits/note-references.ts
+const NOTE_REFERENCE_MARK = "footnoteRef";
+const DELETION_MARK = "deletion";
+const HIDDEN_MARK = "hidden";
+/** The reference a text node carries, or `null` for ordinary text. */
+const noteReferenceOf = (node) => {
+	if (!node.isText) return null;
+	const mark = node.marks.find((candidate) => candidate.type.name === NOTE_REFERENCE_MARK);
+	if (!mark) return null;
+	return {
+		noteType: mark.attrs["noteType"] === "endnote" ? "endnote" : "footnote",
+		noteId: String(mark.attrs["id"])
+	};
+};
+const labelKey = ({ noteType, noteId }) => `${noteType}:${noteId}`;
+const isOmittedFromCleanView = (node) => node.marks.some((mark) => mark.type.name === DELETION_MARK || mark.type.name === HIDDEN_MARK);
+/**
+* The one numbering every AI reader of a story shares. The snapshot numbers
+* block by block inside its own walk; `collectNoteReferenceLabels` (with the
+* snapshot, so both skip what the snapshot skips) numbers a whole story.
+*/
+const createNoteReferenceLabeler = () => {
+	const labels = /* @__PURE__ */ new Map();
+	const numbering = createNoteReferenceNumbering();
+	return {
+		labelOf: (reference) => labels.get(labelKey(reference)),
+		numberBlock: (block) => {
+			block.descendants((node) => {
+				const reference = noteReferenceOf(node);
+				if (reference === null || isOmittedFromCleanView(node)) return true;
+				const { displayNumber, first } = numbering.next(reference.noteType, reference.noteId);
+				if (first) labels.set(labelKey(reference), noteReferenceMarker(reference.noteType, displayNumber));
+				return true;
+			});
+		}
+	};
+};
+/**
+* The text a reader shows for an inline text node: a note reference's marker
+* instead of its package id. A reference the clean view omits (a tracked
+* deletion) has no number there, and reads as an unnumbered marker.
+*/
+const readerTextOf = (node, labels) => {
+	const reference = noteReferenceOf(node);
+	if (reference === null) return node.text ?? "";
+	return labels.labelOf(reference) ?? (reference.noteType === "endnote" ? UNNUMBERED_ENDNOTE_MARKER : UNNUMBERED_FOOTNOTE_MARKER);
+};
+const UNNUMBERED_FOOTNOTE_MARKER = "[^?]";
+const UNNUMBERED_ENDNOTE_MARKER = "[^e?]";
+/** The markers lying wholly inside clean text `[start, end)`, relative to `start`. */
+const noteReferenceSpansWithin = ({ structuralBoundaries }, start, end) => structuralBoundaries.flatMap((boundary) => boundary.type === "noteReference" && boundary.offset >= start && boundary.offset + boundary.length <= end ? [{
+	offset: boundary.offset - start,
+	length: boundary.length
+}] : []);
+/** Whether clean text `[start, end)` starts or ends inside a reference's marker. */
+const cutsIntoNoteReference = ({ structuralBoundaries }, start, end) => structuralBoundaries.some((boundary) => boundary.type === "noteReference" && [start, end].some((offset) => offset > boundary.offset && offset < boundary.offset + boundary.length));
+let comparisonEditsNoteReferences = false;
+/**
+* @internal Run `apply` with its text operations free to remove note
+* references and to write marker text in place of new ones.
+*
+* Only a document comparison does this. Its operations come from a revised
+* document that adds and removes references, so refusing them would drop the
+* edit; each marker it writes is turned back into the reference the revised
+* document holds once the operations land (`compare/inline-atoms.ts`), and a
+* removed reference is a tracked deletion of the reference itself. Every other
+* caller keeps the protection. The scope is synchronous, like the applier.
+*/
+const withComparisonNoteReferenceEdits = (apply) => {
+	const previous = comparisonEditsNoteReferences;
+	comparisonEditsNoteReferences = true;
+	try {
+		return apply();
+	} finally {
+		comparisonEditsNoteReferences = previous;
+	}
+};
+/** @internal Whether the running apply belongs to a comparison (see above). */
+const noteReferenceEditsAllowed = () => comparisonEditsNoteReferences;
+const NOTE_MARKER_PATTERN = /\[\^e?[1-9]\d*\]/gu;
+const markerCount = (text) => text.match(NOTE_MARKER_PATTERN)?.length ?? 0;
+/**
+* Pair a text replacement with the reference markers its source holds.
+*
+* A reference is not text, so a replacement may only rewrite the prose around
+* it: every marker of `source` has to reappear in `replacement`, in order, and
+* the prose between two markers becomes the prose between the same two. A
+* replacement that drops, reorders or rewrites a marker — or writes a new
+* marker-shaped string, which would read as a reference and be none — answers
+* `null`: the edit is refused rather than deleting a reference, or leaving
+* text behind that claims to be one.
+*/
+const segmentsAroundNoteReferences = (source, replacement, spans) => {
+	const segments = {
+		source: [],
+		replacement: []
+	};
+	let sourceCursor = 0;
+	let replacementCursor = 0;
+	for (const { offset, length } of spans) {
+		const marker = source.slice(offset, offset + length);
+		const at = replacement.indexOf(marker, replacementCursor);
+		if (at === -1) return null;
+		segments.source.push({
+			offset: sourceCursor,
+			text: source.slice(sourceCursor, offset)
+		});
+		segments.replacement.push(replacement.slice(replacementCursor, at));
+		sourceCursor = offset + length;
+		replacementCursor = at + marker.length;
+	}
+	segments.source.push({
+		offset: sourceCursor,
+		text: source.slice(sourceCursor)
+	});
+	segments.replacement.push(replacement.slice(replacementCursor));
+	for (const [index, piece] of segments.replacement.entries()) if (markerCount(piece) > markerCount(segments.source[index]?.text ?? "")) return null;
+	const sourceProse = segments.source.map(({ text }) => text).join("");
+	const replacementProse = segments.replacement.join("");
+	if (markerCount(replacementProse) > markerCount(sourceProse)) return null;
+	return segments;
+};
+/**
+* Plan a replacement's changes piece by piece between the markers it keeps, so
+* no change ever touches a reference. `null` when the replacement does not
+* keep them (see {@link segmentsAroundNoteReferences}).
+*/
+const planChangesAroundNoteReferences = (source, replacement, spans, planChanges) => {
+	const segments = segmentsAroundNoteReferences(source, replacement, spans);
+	if (segments === null) return null;
+	return segments.source.flatMap(({ offset, text }, index) => planChanges(text, segments.replacement[index] ?? "").map((change) => ({
+		start: change.start + offset,
+		end: change.end + offset,
+		text: change.text
+	})));
+};
+//#endregion
+export { createNoteReferenceLabeler, cutsIntoNoteReference, noteReferenceEditsAllowed, noteReferenceOf, noteReferenceSpansWithin, planChangesAroundNoteReferences, readerTextOf, segmentsAroundNoteReferences, withComparisonNoteReferenceEdits };